共用方式為

Recall DLP 提供者 API

Recall （預覽）讓使用者能利用自然語言搜尋本地儲存並分析的螢幕快照。 Recall 與資料遺失防護（Data Loss Prevention，簡稱 Data Loss Prevention）DLP供應商整合，防止根據組織政策儲存敏感內容。 本文介紹了能與任何Recall工具合作的公開 APIDLP。

系統架構

下圖顯示 Windows Recall 如何與你的 DLP 提供者互動：

┌─────────────────────────────────────────────────────────────┐
│ Windows Recall                                              │
│ - Captures screenshots and app content                      │
│ - Queries DLP provider before capturing                     │
└─────────────────────┬───────────────────────────────────────┘
                      │ Query: Should we capture this window?
                      │ Context: Process, Window, File, Labels
                      ▼
┌─────────────────────────────────────────────────────────────┐
│ AIContext.exe Process                                       │
│                                                             │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Your DLP Provider DLL (loaded in-process)               │ │
│ │ - Evaluates organizational policies                     │ │
│ │ - Returns capture restrictions                          │ │
│ │ - Provides sensitivity label information                │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────┘
                      │ Response: Allow/Block/Warn/Audit
                      │ Labels: Sensitivity information
                      ▼
┌─────────────────────────────────────────────────────────────┐
│ Windows Recall                                              │
│ - Enforces returned restrictions                            │
│ - Displays sensitivity labels to user                       │
│ - Logs audit events as required                             │
└─────────────────────────────────────────────────────────────┘

公用 API

核心結構

限制執行列舉

定義特定限制的執法程度。

enum RestrictionEnforcement
{
    RestrictionEnforcement_Allow = 0,
    RestrictionEnforcement_AuditAndAllow = 1,
    RestrictionEnforcement_Warn = 2,
    RestrictionEnforcement_Block = 3,
};

值：

  • RestrictionEnforcement_Allow （0）：此操作無限制地被允許。
  • RestrictionEnforcement_AuditAndAllow （1）：操作是允許的，但應記錄以供稽核。
  • RestrictionEnforcement_Warn （2）：操作在繼續前會提示使用者警告。
  • RestrictionEnforcement_Block （3）：手術完全被阻止。

限制結構

規定各項行動的執行等級。

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

成員：

  • CopyToClipboard：將內容複製到剪貼簿的執行等級。
  • CaptureInRecall：擷取快照內容 Recall 的執法等級。

敏感性標籤描述結構

提供使用者可顯示的敏感性標籤資訊。

struct SensitivityLabelDescription
{
    LPCWSTR Name;
    LPCWSTR Color;
    LPCWSTR TooltipText;
    uint32_t Sensitivity;
};

成員：

  • 名稱：顯示敏感標籤的名稱（例如「機密」）。
  • 顏色：用於視覺表現的十六進位顏色代碼（例如「#FF0000」）。
  • 提示文字：使用者將滑鼠移到標籤上時會顯示的描述文字。
  • 靈敏度：數值靈敏度等級（數值越高表示靈敏度越高）。

EnterpriseContextQuery 結構

包含擷取請求及提供者回應 DLP 的資訊。

struct EnterpriseContextQuery
{
    uint32_t ProcessId;
    uint64_t WindowHandle;
    LPCWSTR FileName;
    LPCWSTR SensitivityLabelId;
    LPCWSTR OrganizationId;
    SensitivityLabelDescription SensitivityLabelDescription;
    Restrictions Restrictions;
};

成員：

  • ProcessId：要擷取應用程式的程序 ID。
  • WindowHandle：被擷取視窗的 handle 。
  • 檔案名稱：應用程式中開啟檔案的完整路徑（如適用）。
  • SensitivityLabelId：任何現有敏感標籤的識別碼。
  • OrganizationId：來自當前使用者情境的組織識別碼。
  • SensitivityLabelDescription：將顯示的敏感度標籤資訊（由提供者填入）。
  • 限制：需執行的捕獲限制（由提供者填入）。

備註

應用程式可以透過 API 提供敏感性標籤資訊 UserActivity.ContentInfo 。 關於應用程式應如何格式化及提供此資訊的詳細資訊，請參閱「與使用者活動內容資訊提供敏感性標籤Recall」。

必須的 DLL 匯出

您的 DLP 服務提供商 DLL 必須匯出這些函式，並附上所示的精確名稱：

EnterpriseContextProvider_QueryEnterpriseContext

Recall 呼叫此函式以評估擷取請求。

HRESULT STDMETHODCALLTYPE EnterpriseContextProvider_QueryEnterpriseContext(
    _In_ ULONG totalQuerySizeBytes,
    _Inout_updates_all_(totalQuerySizeBytes / sizeof(EnterpriseContextQuery)) EnterpriseContextQuery* queryBuffer);

參數：

  • totalQuerySizeBytes：查詢緩衝區的總大小（以位元組為單位）。
  • queryBuffer：指向一組 EnterpriseContextQuery 結構的指標。 你的醫療提供者應該根據組織政策更新 Restrictions and SensitivityLabelDescription 欄位。

報酬價值：

  • 成功時回傳 S_OK ，失敗時則有適當的 HRESULT 錯誤代碼。

備註：

Windows 可能會同時發送多個查詢以提升效率。 你的實作應該會處理緩衝區中的所有查詢，並在回傳前更新適當的欄位。

EnterpriseContextProvider_FlushEnterpriseContext

Recall 定期呼叫此函式，讓您的提供者釋放快取的字串或資源。

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

備註：

Recall 在檢查或複製先前查詢回應的資料後，呼叫此函式。 使用此函式來釋放資源、清除快取或執行清理操作。

醫療提供者註冊

登錄檔設定（提供者）

你的 DLP 服務提供者安裝會建立一個登錄檔條目，裡面包含通往你 DLL 的路徑：

HKEY_LOCAL_MACHINE\SOFTWARE\YourCompany\DLP
    InstallPath    REG_SZ    C:\Program Files\YourCompany\DLP

安全性考量：

加強登錄金鑰以防止未經授權的修改。 設定適當的 ACL，限制寫入權限僅限管理員。

群組政策設定（管理員）

管理員透過 設定資料遺失防止提供者 群組政策來配置您的提供者：

  • 保單名稱： SetDataLossPreventionProvider
  • 政策位置：電腦組態 > 管理範本 > Windows 元件 > Windows AI
  • 保單價值格式： key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

要： 該 value 欄位指的是註冊 key表鍵下的登錄檔值名稱，由 指定。

範例配置：

如果你用以下方式建立登錄清單條目：

reg add HKLM\Software\YourCompany\DLP -v InstallPath -t REG_SZ -d "C:\Program Files\YourCompany\DLP"

你的 DLL 名稱為 YourCompanyDLP.dll，群組政策值為：

key:HKLM\software\YourCompany\DLP; value:InstallPath; binary:YourCompanyDLP.dll

可選版本檢查功能：

您可以為您的服務提供者指定最低要求版本 DLP ：

key:HKLM\software\YourCompany\DLP; value:InstallPath; binary:YourCompanyDLP.dll; minversion:1.2.0.0

如果你指定一個 minversion，只有 Recall 當二進位的版本等於或大於指定版本時，才會載入你的二進位檔。

查詢處理流程

典型的交互作用序列

  1. 窗戶 Recall 準備從應用程式視窗擷取內容。

  2. Recall 建立 包括以下內容的查詢：

    • 目標應用程式的程序 ID 與視窗代碼
    • 檔案路徑（如果應用程式有開啟文件）
    • 任何現有的敏感度標籤資訊
    • 來自目前使用者情境的組織識別碼

  3. 尒 DLP 提供者會根據 組織政策評估每個查詢：

    • 檢查申請是否應該被擷取
    • 驗證檔案層級的限制
    • 評估敏感性標籤
    • 套用使用者/群組專屬政策

  4. 您的服務提供者會回傳 更新的查詢結構，包含：

    • Restrictions.CaptureInRecall： 是允許、警告、審核或封鎖擷取
    • SensitivityLabelDescription： 標籤名稱、顏色及顯示工具提示
    • 其他相關的限制資訊

  5. Windows Recall 會強制執行 回傳的限制：

    • 允許：正常吃子
    • AuditAndAllow：擷取並記錄動作
    • 警告：在捕捉前提示使用者
    • 格擋：完全防止被捕獲

範例查詢情境 1：帶有「機密」標籤的 Word 文件

輸入：

  • 過程： winword.exe
  • 檔案： SecretProject.docx
  • 標籤：Confidential

你的處理流程：

請依照組織規則核對文件分類政策。

輸出：

  • CaptureInRecall： RestrictionEnforcement_Block
  • SensitivityLabelDescription.Name：「機密 - 禁止捕捉」

範例查詢情境 2：公開網站上的網頁瀏覽器

輸入：

  • 過程： msedge.exe
  • 窗： news.example.com

你的處理流程：

請與核準清單核對網域。

輸出：

  • CaptureInRecall： RestrictionEnforcement_Allow

範例查詢情境三：財務申請

輸入：

  • 過程： FinanceApp.exe
  • 使用者：finance_user

你的處理流程：

請檢查使用者群組和應用程式靈敏度。

輸出：

  • CaptureInRecall： RestrictionEnforcement_AuditAndAllow
  • SensitivityLabelDescription.Name：「財務數據 - 審核中」

實施指引

效能考量

  • 批次處理：Windows 可能會同時發送多個查詢以提升效率。 優化你的程式碼以處理批次處理。
  • 快取：適當時快取政策決策以改善回應時間。 使用該 FlushEnterpriseContext 函式來管理快取生命週期。
  • 非同步操作：避免查詢函式中的阻塞操作。 請盡快回來，避免影響使用者體驗。

錯誤處理

  • 針對不同錯誤狀況回傳適當的 HRESULT 代碼。
  • 用這個 FlushEnterpriseContext 功能來清理資源。
  • 優雅地處理政策資訊暫時無法取得的情況（預設為安全行為）。

安全性需求

  • In-Process 執行：你的 DLL 在 AIContext.exe 程序中以提升權限執行。
  • 安全編碼實務：遵循安全編碼管理記憶體。 徹底驗證所有輸入參數。
  • 數位簽約：你的 DLL 必須經過 Authenticode 簽署才能部署。 無符號二進位檔不會被載入。
  • 登錄檔保護：強化群組政策中指定的登錄金鑰，以防止未經授權的修改。

載入過程

Recall 用 LoadLibraryEx 來從登錄檔指定的路徑載入你的 DLL，然後呼叫 GetProcAddress 以取得所需匯出函式的位址。 撥打 QueryEnterpriseContext後， Recall 會檢視並複製回應資料，然後致電 FlushEnterpriseContext 讓服務提供者釋放分配的資源。

開始

請依照以下步驟建立並部署您的 DLP 服務提供者：

  1. 透過實作所需的匯出來開發你的 DLL：

    • EnterpriseContextProvider_QueryEnterpriseContext
    • EnterpriseContextProvider_FlushEnterpriseContext

  2. 用範例查詢測試你的實作，確保在不同情境下的行為正確。

  3. 用 Authenticode 憑證簽署你的二進位檔案。

  4. 建立安裝流程 ，能夠：

    • 將你的 DLL 安裝到安全位置
    • 用適當的 ACL 設定登錄檔條目
    • 提供管理員的設定工具

  5. 提供群組原則指示 ，讓管理員設定 SetDataLossPreventionProvider 該政策。

  6. 在企業環境中部署與配置。

  • Last updated on