Recall DLP API do provedor

Recall (versão prévia) permite que os usuários pesquisem instantâneos salvos e analisados localmente de sua tela usando linguagem natural. Recall integra-se com provedores de Prevenção contra Perda de Dados (DLP) para impedir o armazenamento de conteúdo confidencial com base em políticas organizacionais. Este artigo descreve a API pública que permite Recall trabalhar com qualquer DLP ferramenta.

Arquitetura de sistema

O diagrama a seguir mostra como o Windows Recall interage com seu DLP provedor:

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

Enumeração RestrictionEnforcement

Define o nível de imposiçã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 registrada para fins de auditoria.
• RestrictionEnforcement_Warn (2): a operação solicita ao usuário um aviso antes de prosseguir.
• RestrictionEnforcement_Block (3): a operação é totalmente impedida.

Estrutura de restrições

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

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

Membros:

• CopyToClipboard: Nível de imposição para copiar conteúdo para a área de transferência.
• CaptureInRecall: nível de imposição para capturar conteúdo em Recall instantâneos.

Estrutura SensitivityLabelDescription

Fornece informações sobre um rótulo de confidencialidade para exibição ao usuário.

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

Membros:

• Nome: nome de exibição do rótulo de confidencialidade (por exemplo, "Confidencial").
• Cor: código de cor hexadecima para representação visual (por exemplo, "#FF0000").
• TooltipText: texto descritivo mostrado quando o usuário passa o mouse sobre o rótulo.
• Confidencialidade: nível de confidencialidade numérica (valores mais altos indicam maior sensibilidade).

Estrutura EnterpriseContextQuery

Contém informações sobre uma solicitação de captura e a resposta do DLP provedor.

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

Membros:

• ProcessId: ID do processo do aplicativo a ser capturado.
• WindowHandle: manipule para a janela que está sendo capturada.
• FileName: caminho completo para o arquivo aberto no aplicativo (se aplicável).
• SensitivityLabelId: identificador de qualquer rótulo de confidencialidade existente.
• OrganizationId: Identificador da organização do contexto atual do usuário.
• SensitivityLabelDescription: informações de rótulo de confidencialidade a serem exibidas (populadas por provedor).
• Restrições: restrições de captura a serem impostas (populadas pelo provedor).

Exportações de DLL necessárias

A DLP DLL do provedor deve exportar essas funções com os nomes exatos mostrados:

EnterpriseContextProvider_QueryEnterpriseContext

Recall chama essa função para avaliar solicitações 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: ponteiro para uma matriz de EnterpriseContextQuery estruturas. Seu provedor deve atualizar os campos e Restrictions os SensitivityLabelDescription campos com base em políticas organizacionais.

Valor retornado:

• Retorna S_OK com êxito ou um código de erro apropriado HRESULT sobre falha.

Comentários:

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

EnterpriseContextProvider_FlushEnterpriseContext

Recall chama essa função periodicamente para permitir que seu provedor libere cadeias de caracteres ou recursos armazenados em cache.

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

Comentários:

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

Registro do provedor

Configuração do Registro (Provedor)

A DLP instalação do provedor cria uma entrada do Registro que contém o caminho para a DLL:

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

Considerações de segurança:

Proteja a chave do Registro para evitar modificações não autorizadas. Defina as ACLs apropriadas para restringir o acesso de gravação somente aos administradores.

Configuração da Política de Grupo (Administrador)

Os administradores configuram seu provedor por meio da Política de Grupo do Provedor de Prevenção contra Perda de Dados :

• Nome da política: SetDataLossPreventionProvider
• Local da política: Modelos administrativos > de configuração > do computador Windows Components > Windows AI
• Formato de valor da política: key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

Importante: O value campo refere-se ao nome do valor do registro na chave do Registro especificada por key.

Configuração de exemplo:

Se você criar uma entrada do Registro usando:

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

E sua DLL é nomeada YourCompanyDLP.dll, o valor da Política de Grupo é:

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

Verificação de versão opcional:

Você pode especificar uma versão mínima necessária para seu DLP provedor:

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

Se você especificar um minversion, Recall carregará seu binário somente se sua versão for igual ou maior que a versão especificada.

Fluxo de processamento de consulta

Sequência de interação típica

1. Windows Recall se prepara para capturar o conteúdo de uma janela do aplicativo.

2. Recall cria consultas que incluem:

   • ID do processo e identificador de janela do aplicativo de destino
   • Caminho do arquivo (se o aplicativo tiver um documento aberto)
   • Qualquer informação de rótulo de confidencialidade existente
   • ID da organização do contexto atual do usuário

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

   • Verifique se o aplicativo deve ser capturado
   • Verificar restrições no nível do arquivo
   • Avaliar etiquetas de confidencialidade
   • Aplicar políticas específicas de usuário/grupo

4. Seu Provedor retorna estruturas de consulta atualizadas com:

   • Restrictions.CaptureInRecall: seja para permitir, avisar, auditar ou bloquear a captura
   • SensitivityLabelDescription: nome do rótulo, cor e dica de ferramenta para exibição
   • Quaisquer outras informações de restrição relevantes

5. O Windows Recall impõe as restrições retornadas:

   • Permitir: captura normalmente
   • AuditAndAllow: captura e registra a ação em log
   • Avisar: solicita ao usuário antes de capturar
   • Bloquear: impede a captura inteiramente

Exemplo de cenário de consulta 1: Documento do Word com rótulo "Confidencial"

Entrada:

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

Seu processamento:

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

Saída:

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

Exemplo de cenário de consulta 2: navegador da Web no site público

Entrada:

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

Seu processamento:

Verifique o domínio em relação à lista aprovada.

Saída:

• CaptureInRecall: RestrictionEnforcement_Allow

Exemplo de cenário de consulta 3: aplicativo de finanças

Entrada:

• Processo: FinanceApp.exe
• Usuário: finance_user

Seu processamento:

Verifique a confidencialidade do grupo de usuários e do aplicativo.

Saída:

• 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 seu código para lidar com o processamento em lotes.
• Cache: decisões de política de cache quando apropriado para melhorar os tempos de resposta. Use a função para gerenciar o FlushEnterpriseContext ciclo de vida do cache.
• Operações assíncronas: evite operações de bloqueio na função de consulta. Retorne rapidamente para evitar afetar a experiência do usuário.

Tratamento de erros

• Retornar códigos apropriados HRESULT para diferentes condições de erro.
• Use a FlushEnterpriseContext função para limpar os recursos.
• Tratar casos em que as informações da política estão temporariamente indisponíveis normalmente (padrão para comportamento seguro).

Requisitos de segurança

• In-Process execução: sua DLL é executada em processo dentro do processo de AIContext.exe com privilégios elevados.
• Práticas de codificação seguras: siga as práticas de codificação seguras para o gerenciamento de memória. Valide todos os parâmetros de entrada minuciosamente.
• Assinatura digital: sua DLL deve ser assinada por Authenticode para implantação. Binários não assinados não são carregados.
• Proteção do Registro: proteja a chave do Registro especificada na Política de Grupo para evitar modificações não autorizadas.

Processo de carregamento

Recall usa LoadLibraryEx para carregar sua DLL do caminho especificado no registro e, em seguida, chama GetProcAddress para recuperar os endereços das funções exportadas necessárias. Depois de chamar QueryEnterpriseContext, Recall examine e copie dados da resposta e, em seguida, chamadas FlushEnterpriseContext para permitir que seu provedor libere recursos alocados.

Introdução

Siga estas etapas para criar e implantar seu DLP provedor:

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

   • EnterpriseContextProvider_QueryEnterpriseContext
   • EnterpriseContextProvider_FlushEnterpriseContext

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

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

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

   • Instala sua DLL em um local seguro
   • Configura a entrada do Registro com 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. Implante e configure em seu ambiente empresarial.

Links relacionados

• Gerenciar Recall para clientes Windows
• Definir a política do Provedor de Prevenção contra Perda de Dados
• Prevenção Contra Perda de Dados do Microsoft Purview