通过

Recall DLP 提供程序 API

Recall （预览版）允许用户使用自然语言搜索其屏幕的本地保存和分析快照。 Recall 与数据丢失防护 （DLP） 提供程序集成，以防止基于组织策略存储敏感内容。 本文介绍可用于 Recall 使用任何 DLP 工具的公共 API。

系统体系结构

下图显示了 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

核心结构

RestrictionEnforcement 枚举

定义特定限制的强制级别。

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 内容的强制级别。

SensitivityLabelDescription 结构

提供有关要向用户显示的敏感度标签的信息。

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

成员：

  • 名称：敏感度标签的显示名称（例如“机密”）。
  • 颜色：视觉表示形式的十六进制颜色代码（例如“#FF0000”）。
  • TooltipText：当用户将鼠标悬停在标签上时显示的描述性文本。
  • 敏感度：数值敏感度级别（较高的值表示更高的敏感度）。

EnterpriseContextQuery 结构

包含有关捕获请求和提供程序的 DLP 响应的信息。

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

成员：

  • ProcessId：要捕获的应用程序的进程 ID。
  • WindowHandle：正在捕获的窗口的句柄。
  • FileName：在应用程序中打开的文件的完整路径（如果适用）。
  • SensitivityLabelId：任何现有敏感度标签的标识符。
  • OrganizationId：当前用户上下文中的组织标识符。
  • SensitivityLabelDescription：要显示的敏感度标签信息（由提供程序填充）。
  • 限制：捕获要强制实施的限制（由提供程序填充）。

注释

应用程序可以通过 API 提供敏感度标签信息 UserActivity.ContentInfo 。 有关应用程序应如何设置和提供此信息的详细信息，请参阅使用 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 字段 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

如果指定，minversionRecall则仅当二进制文件的版本等于或大于指定版本时，才会加载二进制文件。

查询处理流

典型交互序列

  1. 窗户 Recall 准备从应用程序窗口捕获内容。

  2. Recall 创建 包括：

    • 目标应用程序的进程 ID 和窗口句柄
    • 文件路径（如果应用程序有打开的文档）
    • 任何现有的敏感度标签信息
    • 当前用户上下文中的组织 ID

  3. 你 DLP 提供程序 根据组织策略评估每个查询：

    • 检查是否应捕获应用程序
    • 验证文件级限制
    • 评估敏感度标签
    • 应用特定于用户/组的策略

  4. 提供程序返回更新后的 查询结构，其中包含：

    • Restrictions.CaptureInRecall：是允许、警告、审核还是阻止捕获
    • SensitivityLabelDescription：用于显示的标签名称、颜色和工具提示
    • 任何其他相关的限制信息

  5. Windows Recall 强制实施 返回的限制：

    • 允许：通常捕获
    • AuditAndAllow：捕获和记录作
    • 警告：在捕获之前提示用户
    • 阻止：完全阻止捕获

示例查询方案 1：带有“机密”标签的 Word 文档

输入：

  • 过程： winword.exe
  • 文件：SecretProject.docx
  • 标签：Confidential

正在处理：

根据组织规则检查文档分类策略。

输出：

  • CaptureInRecall: RestrictionEnforcement_Block
  • SensitivityLabelDescription.Name：“机密 - 请勿捕获”

示例查询方案 2：公共网站上的 Web 浏览器

输入：

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

正在处理：

根据已批准的列表检查域。

输出：

  • CaptureInRecall: RestrictionEnforcement_Allow

示例查询方案 3：财务应用程序

输入：

  • 过程： FinanceApp.exe
  • 用户：finance_user

正在处理：

检查用户组和应用程序敏感度。

输出：

  • CaptureInRecall: RestrictionEnforcement_AuditAndAllow
  • SensitivityLabelDescription.Name：“财务数据 - 已审核”

实施指南

性能注意事项

  • 批处理：Windows 可能会同时发送多个查询，以提高效率。 优化代码以处理批处理。
  • 缓存：在适当的时候缓存策略决策以提高响应时间。 使用 FlushEnterpriseContext 函数管理缓存生命周期。
  • 异步作：避免在查询函数中阻止作。 快速返回以防止影响用户体验。

错误处理

  • 返回适用于不同错误条件的相应 HRESULT 代码。
  • 使用 FlushEnterpriseContext 函数清理资源。
  • 处理策略信息暂时不可用（默认为安全行为）的情况。

安全要求

  • In-Process 执行：DLL 使用提升的权限在 AIContext.exe 进程中运行进程内。
  • 安全编码做法：遵循内存管理的安全编码做法。 彻底验证所有输入参数。
  • 数字签名：DLL 必须经过验证码签名才能进行部署。 未签名的二进制文件不会加载。
  • 注册表保护：强化组策略中指定的注册表项，以防止未经授权的修改。

加载过程

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