Recall DLP API de proveedor

Recall (versión preliminar) permite a los usuarios buscar instantáneas guardadas y analizadas localmente de su pantalla mediante lenguaje natural. Recall se integra con proveedores de prevención de pérdida de datos (DLP) para evitar el almacenamiento de contenido confidencial en función de las directivas de la organización. En este artículo se describe la API pública que permite Recall trabajar con cualquier DLP herramienta.

Arquitectura del sistema

En el diagrama siguiente se muestra cómo Interactúa Windows Recall con el DLP proveedor:

┌─────────────────────────────────────────────────────────────┐
│ 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 pública

Estructuras principales

RestrictionEnforcement (enumeración)

Define el nivel de cumplimiento de una restricción específica.

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

Valores:

• RestrictionEnforcement_Allow (0): la operación se permite sin restricciones.
• RestrictionEnforcement_AuditAndAllow (1): se permite la operación, pero se debe registrar con fines de auditoría.
• RestrictionEnforcement_Warn (2): la operación solicita al usuario una advertencia antes de continuar.
• RestrictionEnforcement_Block (3): la operación se impide por completo.

Estructura de restricciones

Especifica el nivel de cumplimiento de varias operaciones.

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

Miembros:

• CopyToClipboard: nivel de cumplimiento para copiar contenido en el Portapapeles.
• CaptureInRecall: nivel de cumplimiento para capturar contenido en Recall instantáneas.

SensitivityLabelDescription (estructura)

Proporciona información sobre una etiqueta de confidencialidad para mostrar al usuario.

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

Miembros:

• Nombre: nombre para mostrar de la etiqueta de confidencialidad (por ejemplo, "Confidencial").
• Color: código de color hexadecimal para la representación visual (por ejemplo, "#FF0000").
• TooltipText: texto descriptivo que se muestra cuando el usuario mantiene el puntero sobre la etiqueta.
• Sensibilidad: nivel de confidencialidad numérico (los valores más altos indican mayor sensibilidad).

EnterpriseContextQuery (estructura)

Contiene información sobre una solicitud de captura y la respuesta del DLP proveedor.

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

Miembros:

• ProcessId: id. de proceso de la aplicación que se va a capturar.
• WindowHandle: identificador de la ventana que se captura.
• FileName: ruta de acceso completa al archivo abierto en la aplicación (si procede).
• SensitivityLabelId: identificador de cualquier etiqueta de confidencialidad existente.
• OrganizationId: identificador de la organización del contexto de usuario actual.
• SensitivityLabelDescription: información de etiqueta de confidencialidad que se va a mostrar (rellenada por proveedor).
• Restricciones: las restricciones de captura que se aplicarán (rellenadas por el proveedor).

Exportaciones de DLL necesarias

El archivo DLL del DLP proveedor debe exportar estas funciones con los nombres exactos que se muestran:

EnterpriseContextProvider_QueryEnterpriseContext

Recall llama a esta función para evaluar las solicitudes de captura.

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

Parámetros:

• totalQuerySizeBytes: tamaño total del búfer de consulta en bytes.
• queryBuffer: puntero a una matriz de EnterpriseContextQuery estructuras. El proveedor debe actualizar los Restrictions campos y SensitivityLabelDescription en función de las directivas de la organización.

Valor devuelto:

• Devuelve S_OK el resultado correcto o un código de error adecuado HRESULT en caso de error.

Observaciones:

Windows puede enviar varias consultas al mismo tiempo para mejorar la eficacia. La implementación debe procesar todas las consultas en el búfer y actualizar los campos adecuados antes de devolver.

EnterpriseContextProvider_FlushEnterpriseContext

Recall llama a esta función periódicamente para permitir que el proveedor libere cadenas o recursos almacenados en caché.

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

Observaciones:

Recall llama a esta función después de examinar o copiar datos de una respuesta de consulta anterior. Use esta función para desasignar los recursos, borrar cachés o realizar operaciones de limpieza.

Registro del proveedor

Configuración del Registro (proveedor)

La DLP instalación del proveedor crea una entrada del Registro que contiene la ruta de acceso al archivo DLL:

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

Consideraciones de seguridad:

Proteja la clave del Registro para evitar modificaciones no autorizadas. Establezca las ACL adecuadas para restringir el acceso de escritura solo a los administradores.

Configuración de directiva de grupo (administrador)

Los administradores configuran el proveedor mediante la directiva de grupo Establecer proveedor de prevención de pérdida de datos :

• Nombre de directiva: SetDataLossPreventionProvider
• Ubicación de la directiva: Configuración del > equipo Plantillas > administrativas Componentes de > Windows AI de Windows
• Formato de valor de directiva: key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

Importante: El value campo hace referencia al nombre del valor del Registro en la clave del Registro especificada por key.

Configuración de ejemplo:

Si crea una entrada del Registro mediante:

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

Y el archivo DLL se denomina YourCompanyDLP.dll, el valor de la directiva de grupo es:

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

Comprobación de versiones opcional:

Puede especificar una versión mínima necesaria para el DLP proveedor:

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

Si especifica un minversion, Recall carga el binario solo si su versión es igual o mayor que la versión especificada.

Flujo de procesamiento de consultas

Secuencia de interacción típica

1. Windows Recall se prepara para capturar contenido desde una ventana de aplicación.

2. Recall crea consultas que incluyen:

   • Identificador de proceso y identificador de ventana de la aplicación de destino
   • Ruta de acceso del archivo (si la aplicación tiene un documento abierto)
   • Cualquier información de etiqueta de confidencialidad existente
   • Id. de organización del contexto de usuario actual

3. Usted DLP El proveedor evalúa cada consulta en las directivas organizativas:

   • Compruebe si se debe capturar la aplicación.
   • Comprobación de las restricciones de nivel de archivo
   • Evaluación de etiquetas de confidencialidad
   • Aplicación de directivas específicas del usuario o grupo

4. El proveedor devuelve estructuras de consulta actualizadas con:

   • Restrictions.CaptureInRecall: indica si se debe permitir, advertir, auditar o bloquear la captura.
   • SensitivityLabelDescription: nombre de etiqueta, color y información sobre herramientas para mostrar
   • Cualquier otra información de restricción pertinente

5. Windows Recall aplica las restricciones devueltas:

   • Permitir: capturas normalmente
   • AuditAndAllow: captura y registra la acción
   • Advertir: solicita al usuario antes de capturar
   • Bloquear: impide la captura por completo

Escenario de consulta de ejemplo 1: Documento de Word con etiqueta "Confidencial"

Entrada:

• Proceso: winword.exe
• Archivo: SecretProject.docx
• Etiqueta: Confidential

Su procesamiento:

Compruebe la directiva de clasificación de documentos con respecto a las reglas organizativas.

Salida:

• CaptureInRecall: RestrictionEnforcement_Block
• SensitivityLabelDescription.Name: "Confidencial - No capturar"

Escenario de consulta de ejemplo 2: Explorador web en el sitio público

Entrada:

• Proceso: msedge.exe
• Ventana: news.example.com

Su procesamiento:

Compruebe el dominio en la lista aprobada.

Salida:

• CaptureInRecall: RestrictionEnforcement_Allow

Escenario de consulta de ejemplo 3: Aplicación financiera

Entrada:

• Proceso: FinanceApp.exe
• Usuario: finance_user

Su procesamiento:

Compruebe la confidencialidad del grupo de usuarios y de la aplicación.

Salida:

• CaptureInRecall: RestrictionEnforcement_AuditAndAllow
• SensitivityLabelDescription.Name: "Finance Data - Audited"

Directrices de implementación

Consideraciones de rendimiento

• Procesamiento por lotes: Windows puede enviar varias consultas al mismo tiempo para ser más eficientes. Optimice el código para controlar el procesamiento por lotes.
• Almacenamiento en caché: decisiones de directiva de caché cuando corresponda para mejorar los tiempos de respuesta. Use la función para administrar el ciclo de vida de la FlushEnterpriseContext memoria caché.
• Operaciones asincrónicas: evite las operaciones de bloqueo en la función de consulta. Vuelva rápidamente para evitar que afecte a la experiencia del usuario.

Tratamiento de errores

• Devuelve los códigos adecuados HRESULT para diferentes condiciones de error.
• Use la FlushEnterpriseContext función para limpiar los recursos.
• Controlar los casos en los que la información de la directiva no está disponible temporalmente (el comportamiento predeterminado es seguro).

Requisitos de seguridad

• In-Process ejecución: el archivo DLL se ejecuta en proceso dentro del proceso de AIContext.exe con privilegios elevados.
• Prácticas de codificación seguras: siga los procedimientos de codificación seguros para la administración de memoria. Valide todos los parámetros de entrada exhaustivamente.
• Firma digital: el archivo DLL debe estar firmado con Authenticode para la implementación. Los archivos binarios sin firmar no se cargan.
• Protección del Registro: proteja la clave del Registro especificada en la directiva de grupo para evitar modificaciones no autorizadas.

Proceso de carga

Recall usa LoadLibraryEx para cargar el archivo DLL desde la ruta de acceso especificada en el Registro y, a continuación, llama GetProcAddress a para recuperar las direcciones de las funciones exportadas necesarias. Después de llamar a QueryEnterpriseContext, Recall examina y copia los datos de la respuesta y, a continuación, llama FlushEnterpriseContext a para permitir que el proveedor libere recursos asignados.

Comienza

Siga estos pasos para crear e implementar el DLP proveedor:

1. Desarrolle el archivo DLL mediante la implementación de las exportaciones necesarias:

   • EnterpriseContextProvider_QueryEnterpriseContext
   • EnterpriseContextProvider_FlushEnterpriseContext

2. Pruebe la implementación con consultas de ejemplo para garantizar un comportamiento correcto en distintos escenarios.

3. Firme el binario con un certificado Authenticode.

4. Cree un proceso de instalación que:

   • Instala el archivo DLL en una ubicación segura.
   • Configura la entrada del Registro con las ACL adecuadas.
   • Proporciona herramientas de configuración para administradores

5. Proporcione instrucciones de directiva de grupo para que los administradores configuren la SetDataLossPreventionProvider directiva.

6. Implemente y configure en el entorno empresarial.

Vínculos relacionados

• Administrar Recall para clientes de Windows
• Establecimiento de la directiva del proveedor de prevención de pérdida de datos
• Prevención de pérdida de datos de Microsoft Purview