Partager via

Recall DLP API fournisseur

Recall (préversion) permet aux utilisateurs de rechercher localement des instantanés enregistrés et analysés de leur écran à l’aide du langage naturel. Recall s’intègre aux fournisseurs de protection contre la perte de données (DLP) pour empêcher le stockage de contenu sensible en fonction des stratégies organisationnelles. Cet article décrit l’API publique qui permet Recall d’utiliser n’importe quel DLP outil.

Architecture du système

Le diagramme suivant montre comment Windows Recall interagit avec votre DLP fournisseur :

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

Structures principales

RestrictionEnforcement, énumération

Définit le niveau d’application d’une restriction spécifique.

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

Valeurs:

  • RestrictionEnforcement_Allow (0) : l’opération est autorisée sans restrictions.
  • RestrictionEnforcement_AuditAndAllow (1) : l’opération est autorisée, mais doit être enregistrée à des fins d’audit.
  • RestrictionEnforcement_Warn (2) : l’opération invite l’utilisateur à afficher un avertissement avant de continuer.
  • RestrictionEnforcement_Block (3) : l’opération n’est pas entièrement évitée.

Restrictions Structure

Spécifie le niveau d’application pour différentes opérations.

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

Membres:

  • CopyToClipboard : niveau d’application pour copier du contenu dans le Presse-papiers.
  • CaptureInRecall : niveau d’application pour capturer du contenu dans Recall les instantanés.

SensitivityLabelDescription, structure

Fournit des informations sur une étiquette de confidentialité pour l’affichage à l’utilisateur.

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

Membres:

  • Nom : nom complet de l’étiquette de confidentialité (par exemple, « Confidentiel »).
  • Couleur : code de couleur hexadécimal pour la représentation visuelle (par exemple, « #FF0000 »).
  • Info-bulleText : texte descriptif affiché lorsque l’utilisateur pointe sur l’étiquette.
  • Sensibilité : niveau de sensibilité numérique (les valeurs supérieures indiquent une plus grande sensibilité).

EnterpriseContextQuery, structure

Contient des informations sur une demande de capture et la réponse du DLP fournisseur.

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

Membres:

  • ProcessId : ID de processus de l’application à capturer.
  • WindowHandle : gérer la fenêtre capturée.
  • FileName : chemin d’accès complet au fichier ouvert dans l’application (le cas échéant).
  • SensitivityLabelId : Identificateur de n’importe quelle étiquette de confidentialité existante.
  • OrganizationId : Identificateur de l’organisation à partir du contexte utilisateur actuel.
  • SensitivityLabelDescription : informations d’étiquette de confidentialité à afficher (renseignées par le fournisseur).
  • Restrictions : les restrictions de capture à appliquer (remplies par le fournisseur).

Note

Les applications peuvent fournir des informations d’étiquette de confidentialité via l’API UserActivity.ContentInfo . Pour plus d’informations sur la façon dont les applications doivent mettre en forme et fournir ces informations, consultez Fournir des étiquettes de confidentialité avec Recall UserActivity ContentInfo.

Exportations DLL requises

La DLL de votre DLP fournisseur doit exporter ces fonctions avec les noms exacts indiqués :

EnterpriseContextProvider_QueryEnterpriseContext

Recall appelle cette fonction pour évaluer les demandes de capture.

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

Paramètres :

  • totalQuerySizeBytes : taille totale de la mémoire tampon de requête en octets.
  • queryBuffer : pointeur vers un tableau de EnterpriseContextQuery structures. Votre fournisseur doit mettre à jour les champs et Restrictions les SensitivityLabelDescription champs en fonction des stratégies organisationnelles.

Valeur de retour :

  • Retourne S_OK une valeur réussie ou un code d’erreur approprié HRESULT en cas d’échec.

Remarques :

Windows peut envoyer plusieurs requêtes en même temps pour une efficacité. Votre implémentation doit traiter toutes les requêtes dans la mémoire tampon et mettre à jour les champs appropriés avant de retourner.

EnterpriseContextProvider_FlushEnterpriseContext

Recall appelle cette fonction régulièrement pour permettre à votre fournisseur de libérer des chaînes ou des ressources mises en cache.

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

Remarques :

Recall appelle cette fonction après avoir examiné ou copié les données d’une réponse de requête précédente. Utilisez cette fonction pour libérer toutes les ressources, effacer les caches ou effectuer des opérations de nettoyage.

Inscription du fournisseur

Configuration du Registre (fournisseur)

L’installation de votre DLP fournisseur crée une entrée de Registre qui contient le chemin d’accès à votre DLL :

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

Considérations relatives à la sécurité :

Renforcer la clé de Registre pour empêcher toute modification non autorisée. Définissez les listes de contrôle d’accès appropriées pour restreindre l’accès en écriture aux administrateurs uniquement.

Configuration de la stratégie de groupe (administrateur)

Les administrateurs configurent votre fournisseur via la stratégie de groupe définir le fournisseur de protection contre la perte de données :

  • Nom de la stratégie : SetDataLossPreventionProvider
  • Emplacement de stratégie : Modèles > d’administration de configuration > ordinateur Windows Composants > Windows AI
  • Format de valeur de stratégie : key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

Important: Le value champ fait référence au nom de la valeur de Registre sous la clé de Registre spécifiée par key.

Exemple de configuration :

Si vous créez une entrée de Registre à l’aide de :

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

Et votre DLL est nommée YourCompanyDLP.dll, la valeur de la stratégie de groupe est :

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

Vérification de version facultative :

Vous pouvez spécifier une version minimale requise pour votre DLP fournisseur :

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

Si vous spécifiez un minversion, Recall charge votre binaire uniquement si sa version est égale ou supérieure à la version spécifiée.

Flux de traitement des requêtes

Séquence d’interaction classique

  1. Windows Recall prépare à capturer du contenu à partir d’une fenêtre d’application.

  2. Recall crée des requêtes qui incluent :

    • ID de processus et handle de fenêtre de l’application cible
    • Chemin d’accès au fichier (si l’application a un document ouvert)
    • Toutes les informations d’étiquette de confidentialité existantes
    • ID d’organisation à partir du contexte utilisateur actuel

  3. Votre DLP Le fournisseur évalue chaque requête par rapport aux stratégies organisationnelles :

    • Vérifier si l’application doit être capturée
    • Vérifier les restrictions au niveau du fichier
    • Évaluer les étiquettes de confidentialité
    • Appliquer des stratégies spécifiques à l’utilisateur/au groupe

  4. Votre fournisseur retourne des structures de requête mises à jour avec :

    • Restrictions.CaptureInRecall: indique s’il faut autoriser, avertir, auditer ou bloquer la capture
    • SensitivityLabelDescription: Nom d’étiquette, couleur et info-bulle pour l’affichage
    • Toute autre information de restriction pertinente

  5. Windows Recall applique les restrictions retournées :

    • Autoriser : Captures normalement
    • AuditAndAllow : Capture et journalise l’action
    • Avertissement : invite l’utilisateur avant la capture
    • Bloquer : empêche la capture entièrement

Exemple de scénario de requête 1 : Document Word avec étiquette « Confidentiel »

Entrée :

  • Processus: winword.exe
  • Lime: SecretProject.docx
  • Étiquette : Confidential

Votre traitement :

Vérifiez la stratégie de classification des documents par rapport aux règles organisationnelles.

Output:

  • CaptureInRecall: RestrictionEnforcement_Block
  • SensitivityLabelDescription.Name: « Confidentiel - Ne pas capturer »

Exemple de scénario de requête 2 : Navigateur web sur un site public

Entrée :

  • Processus: msedge.exe
  • Fenêtre: news.example.com

Votre traitement :

Vérifiez le domaine par rapport à la liste approuvée.

Output:

  • CaptureInRecall: RestrictionEnforcement_Allow

Exemple de scénario de requête 3 : Application finance

Entrée :

  • Processus: FinanceApp.exe
  • Utilisateur : finance_user

Votre traitement :

Vérifiez la sensibilité du groupe d’utilisateurs et de l’application.

Output:

  • CaptureInRecall: RestrictionEnforcement_AuditAndAllow
  • SensitivityLabelDescription.Name: « Données financières - Auditées »

Instructions d’implémentation

Considérations relatives aux performances

  • Traitement par lots : Windows peut envoyer plusieurs requêtes en même temps pour être plus efficace. Optimisez votre code pour gérer le traitement par lots.
  • Mise en cache : décisions de stratégie de cache en cas de besoin pour améliorer les temps de réponse. Utilisez la fonction pour gérer le FlushEnterpriseContext cycle de vie du cache.
  • Opérations asynchrones : évitez les opérations bloquantes dans la fonction de requête. Revenez rapidement pour empêcher l’impact sur l’expérience utilisateur.

Gestion des erreurs

  • Retourne les codes appropriés HRESULT pour différentes conditions d’erreur.
  • Utilisez la FlushEnterpriseContext fonction pour nettoyer les ressources.
  • Gérer les cas où les informations de stratégie sont temporairement indisponibles correctement (par défaut, comportement sécurisé).

Besoins de sécurité

  • In-Process exécution : votre DLL s’exécute en cours dans le processus de AIContext.exe avec des privilèges élevés.
  • Pratiques de codage sécurisées : suivez les pratiques de codage sécurisées pour la gestion de la mémoire. Validez soigneusement tous les paramètres d’entrée.
  • Signature numérique : votre DLL doit être signée Authenticode pour le déploiement. Les fichiers binaires non signés ne sont pas chargés.
  • Protection du Registre : renforcez la clé de Registre spécifiée dans la stratégie de groupe pour empêcher les modifications non autorisées.

Processus de chargement

Recall utilise LoadLibraryEx pour charger votre DLL à partir du chemin spécifié dans le Registre, puis appelle GetProcAddress pour récupérer les adresses des fonctions exportées requises. Après avoir appelé QueryEnterpriseContext, Recall examine et copie les données de la réponse, puis appelle FlushEnterpriseContext pour permettre à votre fournisseur de libérer des ressources allouées.

Get started

Procédez comme suit pour créer et déployer votre DLP fournisseur :

  1. Développez votre DLL en implémentant les exportations requises :

    • EnterpriseContextProvider_QueryEnterpriseContext
    • EnterpriseContextProvider_FlushEnterpriseContext

  2. Testez votre implémentation avec des exemples de requêtes pour garantir un comportement correct dans différents scénarios.

  3. Signez votre fichier binaire avec un certificat Authenticode.

  4. Créez un processus d’installation qui :

    • Installe votre DLL à un emplacement sécurisé
    • Configure l’entrée de Registre avec les listes de contrôle d’accès appropriées
    • Fournit des outils de configuration pour les administrateurs

  5. Fournissez des instructions de stratégie de groupe aux administrateurs pour configurer la SetDataLossPreventionProvider stratégie.

  6. Déployez et configurez dans votre environnement d’entreprise.

  • Last updated on