Recall DLP API do Provedor

Recall (Pré-visualização) permite aos utilizadores pesquisar instantâneos guardados e analisados localmente do seu ecrã, utilizando linguagem natural. Recall integra-se com fornecedores de Prevenção de Perda de Dados (DLP) para evitar o armazenamento de conteúdos sensíveis com base nas políticas organizacionais. Este artigo descreve a API pública que permite Recall trabalhar com qualquer DLP ferramenta.

Arquitetura do sistema

O diagrama seguinte mostra como o Windows Recall interage com o seu DLP fornecedor:

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

Estruturas Centrais

Enumeração de Aplicação de Restrições

Define o nível de aplicação para uma restrição específica.

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

Valores:

• RestrictionEnforcement_Allow (0): A operação é permitida sem restrições.
• RestrictionEnforcement_AuditAndAllow (1): A operação é permitida, mas deve ser registada para efeitos de auditoria.
• RestrictionEnforcement_Warn (2): A operação avisa o utilizador antes de prosseguir.
• RestrictionEnforcement_Block (3): A operação é totalmente impedida.

Estrutura de Restrições

Especifica o nível de fiscalização para várias operações.

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

Membros:

• CopyToClipboard: Nível de aplicação para copiar conteúdo para a prancheta.
• CaptureInRecall: Nível de aplicação para captura de conteúdo em Recall instantâneos.

Estrutura SensibilidadeEtiquetaDescrição

Fornece informações sobre uma etiqueta de sensibilidade para exibição ao utilizador.

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

Membros:

• Nome: Nome de exibição do rótulo de sensibilidade (por exemplo, "Confidencial").
• Cor: Código de cor hexadecimal para representação visual (por exemplo, "#FF0000").
• TooltipText: Texto descritivo mostrado quando o utilizador paira sobre a etiqueta.
• Sensibilidade: Nível de sensibilidade numérica (valores mais altos indicam maior sensibilidade).

Estrutura EnterpriseContextQuery

Contém informações sobre um pedido de captura e a resposta do DLP fornecedor.

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

Membros:

• ProcessId: ID do processo da aplicação a capturar.
• WindowHandle: Pega para a janela que está a ser capturada.
• FileName: Caminho completo para o ficheiro aberto na aplicação (se aplicável).
• SensibilityLabelId: Identificador de qualquer etiqueta de sensibilidade existente.
• OrganizationId: Identificador da organização do contexto atual do utilizador.
• SensibilidadeEtiquetaDescrição: Informação de etiqueta de sensibilidade a ser exibida (preenchida por fornecedor).
• Restrições: Restrições de captura a serem aplicadas (preenchidas por fornecedor).

Exportações DLL obrigatórias

O DLL do seu DLP fornecedor deve exportar estas funções com os nomes exatos apresentados:

EnterpriseContextProvider_QueryEnterpriseContext

Recall chama esta função para avaliar pedidos de captura.

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

Parâmetros:

• totalQuerySizeBytes: Tamanho total do buffer de consulta em bytes.
• queryBuffer: Apontador para um array de EnterpriseContextQuery estruturas. O seu fornecedor deve atualizar os Restrictions campos e SensitivityLabelDescription com base nas políticas organizacionais.

Valor de Retorno:

• Retornos S_OK em caso de sucesso, ou um código de erro apropriado HRESULT em caso de falha.

Observações:

O Windows pode enviar várias consultas ao mesmo tempo para maior eficiência. A sua implementação deve processar todas as consultas no buffer e atualizar os campos apropriados antes de regressar.

EnterpriseContextProvider_FlushEnterpriseContext

Recall recorre a esta função periodicamente para permitir que o seu fornecedor liberte strings ou recursos em cache.

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

Observações:

Recall chama esta função depois de examinar ou copiar dados de uma resposta de consulta anterior. Use esta função para desalocar recursos, limpar caches ou realizar operações de limpeza.

Registo de prestadores

Configuração do registo (Fornecedor)

A instalação do seu DLP fornecedor cria uma entrada no registo que contém o caminho para a sua DLL:

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

Considerações de segurança:

Endureça a chave do registo para evitar modificações não autorizadas. Defina ACLs apropriadas para restringir o acesso de escrita apenas a administradores.

Configuração de Políticas de Grupo (Administrador)

Os administradores configuram o seu prestador através da Política de Grupo de Prevenção de Perda de Dados para Prestadores :

• Nome da Política: SetDataLossPreventionProvider
• Localização da Política: Configuração > do Computador Modelos Administrativos Componentes > do Windows IA > do Windows
• Formato do Valor da Política: key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

Importante: O value campo refere-se ao nome do valor do registo sob a chave do registo especificada por key.

Exemplo de Configuração:

Se criar uma entrada no registo utilizando:

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

E a sua DLL chama-se YourCompanyDLP.dll, o valor da Política de Grupo é:

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

Verificação Opcional de Versões:

Pode especificar uma versão mínima exigida para o seu DLP fornecedor:

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

Se especificar um minversion, Recall carrega o seu binário apenas se a sua versão for igual ou maior que a versão especificada.

Fluxo de Processamento de Consultas

Sequência típica de interação

1. Janelas Recall prepara-se para capturar conteúdo a partir de uma janela de aplicação.

2. Recall cria consultas que incluem:

   • ID de processo e handle de janela da aplicação alvo
   • Caminho do ficheiro (se a aplicação tiver um documento aberto)
   • Qualquer informação existente sobre etiquetas de sensibilidade
   • ID da organização a partir do contexto atual do utilizador

3. O teu DLP O prestador avalia cada consulta em relação às políticas organizacionais:

   • Verifique se a candidatura deve ser capturada
   • Verificar as restrições ao nível do ficheiro
   • Avaliar etiquetas de sensibilidade
   • Aplicar políticas específicas de utilizador/grupo

4. O seu Prestador devolve estruturas de consulta atualizadas com:

   • Restrictions.CaptureInRecall: Se deve permitir, avisar, auditar ou bloquear a captura
   • SensitivityLabelDescription: Nome da etiqueta, cor e dica de ferramenta para exibição
   • Qualquer outra informação relevante sobre restrições

5. O Windows Recall aplica as restrições devolvidas:

   • Permitir: Captura normalmente
   • AuditAndAllow: Captura e regista a ação
   • Aviso: Avisa o utilizador antes de capturar
   • Bloqueio: Previne totalmente a captura

Exemplo de Cenário de Consulta 1: Documento Word com Rótulo "Confidencial"

Entrada:

• Processo: winword.exe
• Ficheiro: SecretProject.docx
• Rótulo: Confidential

O Seu Processamento:

Verifique a política de classificação de documentos em relação às regras organizacionais.

Output:

• CaptureInRecall: RestrictionEnforcement_Block
• SensitivityLabelDescription.Name: "Confidencial - Não Capturar"

Exemplo de Cenário de Consulta 2: Navegador Web em Site Público

Entrada:

• Processo: msedge.exe
• Janela: news.example.com

O Seu Processamento:

Verifique o domínio com a lista aprovada.

Output:

• CaptureInRecall: RestrictionEnforcement_Allow

Exemplo de Cenário de Consulta 3: Aplicação de Finanças

Entrada:

• Processo: FinanceApp.exe
• Utilizador: finance_user

O Seu Processamento:

Verifique a sensibilidade do grupo de utilizadores e da aplicação.

Output:

• CaptureInRecall: RestrictionEnforcement_AuditAndAllow
• SensitivityLabelDescription.Name: "Dados Financeiros - Auditados"

Diretrizes de Implementação

Considerações sobre desempenho

• Processamento em lote: O Windows pode enviar várias consultas ao mesmo tempo para ser mais eficiente. Otimize o seu código para lidar com processamento em lote.
• Cache: Decisões de políticas de cache quando apropriadas para melhorar os tempos de resposta. Use a FlushEnterpriseContext função para gerir o ciclo de vida da cache.
• Operações Assíncronas: Evite bloquear operações na função de consulta. Volte rapidamente para evitar afetar a experiência do utilizador.

Tratamento de erros

• Devolva códigos apropriados HRESULT para diferentes condições de erro.
• Usa a FlushEnterpriseContext função para limpar recursos.
• Trate de forma elegante casos em que a informação da política está temporariamente indisponível (por defeito para comportamento seguro).

Requisitos de segurança

• In-Process execução: A sua DLL corre em processo dentro do processo AIContext.exe com privilégios elevados.
• Práticas de codificação segura: Siga práticas de codificação segura para a gestão da memória. Valida todos os parâmetros de entrada de forma minuciosa.
• Assinatura digital: O seu DLL deve ser assinado por Authenticode para implementação. Binários sem assinatura não são carregados.
• Proteção do registo: Reforçar a chave do registo especificada na Política de Grupo para evitar modificações não autorizadas.

Processo de carregamento

Recall usa LoadLibraryEx para carregar a sua DLL a partir do caminho especificado no registo, depois chamadas GetProcAddress para recuperar os endereços das funções exportadas necessárias. Após ligar QueryEnterpriseContext, Recall examina e copia os dados da resposta, depois liga FlushEnterpriseContext para permitir que o seu fornecedor liberte os recursos alocados.

Introdução

Siga estes passos para criar e implementar o seu DLP fornecedor:

1. Desenvolva a sua DLL implementando as exportações necessárias:

   • EnterpriseContextProvider_QueryEnterpriseContext
   • EnterpriseContextProvider_FlushEnterpriseContext

2. Teste a sua implementação com consultas de exemplo para garantir o comportamento correto em diferentes cenários.

3. Assine o seu binário com um certificado Authenticode.

4. Crie um processo de instalação que:

   • Instala o seu DLL num local seguro
   • Configura a entrada do registo com as ACLs apropriadas
   • Fornece ferramentas de configuração para administradores

5. Forneça instruções de Política de Grupo para os administradores configurarem a SetDataLossPreventionProvider política.

6. Implemente e configure no seu ambiente empresarial.

Links relacionados

• Gerir Recall para clientes Windows
• Definir política de Prestador de Prevenção de Perda de Dados
• Prevenção de perda de dados do Microsoft Purview