Recall DLP Anbieter-API

Recall (Vorschau) ermöglicht Es Benutzern, lokal gespeicherte und analysierte Momentaufnahmen ihres Bildschirms mithilfe natürlicher Sprache zu durchsuchen. Recall integriert in Anbieter zur Verhinderung von Datenverlust (DLPData Loss Prevention, Verhinderung von Datenverlust), um die Speicherung vertraulicher Inhalte basierend auf Organisationsrichtlinien zu verhindern. In diesem Artikel wird die öffentliche API beschrieben, die es ermöglicht Recall , mit jedem Tool DLP zu arbeiten.

Systemarchitektur

Das folgende Diagramm zeigt, wie Windows Recall mit Ihrem DLP Anbieter interagiert:

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

Öffentliche API

Kernstrukturen

RestrictionEnforcement-Aufzählung

Definiert die Erzwingungsstufe für eine bestimmte Einschränkung.

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

Werte:

• RestrictionEnforcement_Allow (0): Der Vorgang ist ohne Einschränkungen zulässig.
• RestrictionEnforcement_AuditAndAllow (1): Der Vorgang ist zulässig, sollte jedoch zu Überwachungszwecken protokolliert werden.
• RestrictionEnforcement_Warn (2): Der Vorgang fordert den Benutzer vor dem Fortfahren mit einer Warnung auf.
• RestrictionEnforcement_Block (3): Der Vorgang wird vollständig verhindert.

Einschränkungsstruktur

Gibt die Erzwingungsstufe für verschiedene Vorgänge an.

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

Angehörige:

• CopyToClipboard: Erzwingungsstufe zum Kopieren von Inhalten in die Zwischenablage.
• CaptureInRecall: Erzwingungsstufe zum Erfassen von Inhalten in Recall Momentaufnahmen.

SensitivityLabelDescription-Struktur

Stellt Informationen zu einer Vertraulichkeitsbezeichnung bereit, die dem Benutzer angezeigt werden kann.

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

Angehörige:

• Name: Anzeigename der Vertraulichkeitsbezeichnung (z. B. "Vertraulich").
• Farbe: Hex-Farbcode für visuelle Darstellung (z. B. "#FF0000").
• TooltipText: Beschreibender Text, der angezeigt wird, wenn der Benutzer auf die Beschriftung zeigt.
• Vertraulichkeit: Numerische Vertraulichkeitsstufe (höhere Werte deuten auf eine höhere Vertraulichkeit hin).

EnterpriseContextQuery-Struktur

Enthält Informationen zu einer Erfassungsanforderung und der Antwort des DLP Anbieters.

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

Angehörige:

• ProcessId: Prozess-ID der zu erfassenden Anwendung.
• WindowHandle: Handle to the window being captured.
• FileName: Vollständiger Pfad zur Datei, die in der Anwendung geöffnet ist (falls zutreffend).
• SensitivityLabelId: Bezeichner einer vorhandenen Vertraulichkeitsbezeichnung.
• OrganizationId: Organisationsbezeichner aus dem aktuellen Benutzerkontext.
• SensitivityLabelDescription: Informationen zur Vertraulichkeitsbezeichnung, die angezeigt werden sollen (vom Anbieter aufgefüllt).
• Einschränkungen: Erfassungseinschränkungen, die erzwungen werden sollen (vom Anbieter aufgefüllt).

Erforderliche DLL-Exporte

Ihre DLP Anbieter-DLL muss diese Funktionen mit den genauen Namen exportieren, die angezeigt werden:

EnterpriseContextProvider_QueryEnterpriseContext

Recall ruft diese Funktion auf, um Erfassungsanforderungen auszuwerten.

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

Parameter:

• totalQuerySizeBytes: Gesamtgröße des Abfragepuffers in Bytes.
• queryBuffer: Zeiger auf ein Array von EnterpriseContextQuery Strukturen. Ihr Anbieter sollte die Restrictions Felder SensitivityLabelDescription basierend auf Organisationsrichtlinien aktualisieren.

Rückgabewert:

• Gibt S_OK bei Erfolg oder bei einem Fehlercode einen geeigneten HRESULT Fehlercode zurück.

Hinweise:

Windows sendet möglicherweise mehrere Abfragen gleichzeitig zur Effizienz. Ihre Implementierung sollte alle Abfragen im Puffer verarbeiten und die entsprechenden Felder aktualisieren, bevor sie zurückgegeben werden.

EnterpriseContextProvider_FlushEnterpriseContext

Recall ruft diese Funktion regelmäßig auf, damit Ihr Anbieter zwischengespeicherte Zeichenfolgen oder Ressourcen freigibt.

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

Hinweise:

Recall ruft diese Funktion auf, nachdem sie Daten aus einer vorherigen Abfrageantwort untersucht oder kopiert hat. Verwenden Sie diese Funktion, um Ressourcen zuzuordnen, Caches zu löschen oder Bereinigungsvorgänge auszuführen.

Anbieterregistrierung

Registrierungssetup (Anbieter)

Ihre DLP Anbieterinstallation erstellt einen Registrierungseintrag, der den Pfad zu Ihrer DLL enthält:

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

Sicherheitsüberlegungen:

Härtung des Registrierungsschlüssels, um nicht autorisierte Änderungen zu verhindern. Legen Sie geeignete ACLs fest, um den Schreibzugriff nur auf Administratoren einzuschränken.

Gruppenrichtlinienkonfiguration (Administrator)

Administratoren konfigurieren Ihren Anbieter über die Gruppenrichtlinie für den Anbieter für die Verhinderung von Datenverlust:

• Richtlinienname: SetDataLossPreventionProvider
• Richtlinienspeicherort: Administrative Computerkonfigurationsvorlagen >> Windows-Komponenten > Windows AI
• Richtlinienwertformat: key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

Wichtig: Das value Feld bezieht sich auf den Namen des Registrierungswerts unter dem durch key.

Beispielkonfiguration:

Wenn Sie einen Registrierungseintrag erstellen, indem Sie Folgendes verwenden:

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

Und Ihre DLL heißt YourCompanyDLP.dll, der Gruppenrichtlinienwert lautet:

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

Optionale Versionsüberprüfung:

Sie können eine mindest erforderliche Version für Ihren DLP Anbieter angeben:

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

Wenn Sie einen minversionWert angeben, Recall wird die Binärdatei nur geladen, wenn die Version gleich oder größer als die angegebene Version ist.

Abfrageverarbeitungsfluss

Typische Interaktionssequenz

1. Fenster Recall bereitet die Aufnahme von Inhalten aus einem Anwendungsfenster vor.

2. Recall erstellt Abfragen , die Folgendes enthalten:

   • Prozess-ID und Fensterhandle der Zielanwendung
   • Dateipfad (wenn die Anwendung über ein geöffnetes Dokument verfügt)
   • Vorhandene Vertraulichkeitsbezeichnungsinformationen
   • Organisations-ID aus dem aktuellen Benutzerkontext

3. Dein DLP Der Anbieter wertet jede Abfrage anhand von Organisationsrichtlinien aus:

   • Überprüfen, ob die Anwendung erfasst werden soll
   • Überprüfen von Einschränkungen auf Dateiebene
   • Auswerten von Vertraulichkeitsbezeichnungen
   • Anwenden von benutzer-/gruppenspezifischen Richtlinien

4. Ihr Anbieter gibt aktualisierte Abfragestrukturen zurück mit:

   • Restrictions.CaptureInRecall: Gibt an, ob Aufzeichnungen zugelassen, gewarnt, überwacht oder blockiert werden sollen
   • SensitivityLabelDescription: Bezeichnungsname, Farbe und QuickInfo für die Anzeige
   • Alle anderen relevanten Einschränkungsinformationen

5. Windows Recall erzwingt die zurückgegebenen Einschränkungen:

   • Zulassen: Aufzeichnungen normal
   • AuditAndAllow: Erfasst und protokolliert die Aktion.
   • Warn: Fordert den Benutzer vor der Erfassung auf
   • Block: Verhindert die vollständige Erfassung

Beispielabfrageszenario 1: Word-Dokument mit der Bezeichnung "Vertraulich"

Eingabe:

• Prozess: winword.exe
• Datei: SecretProject.docx
• Bezeichnung: Confidential

Ihre Verarbeitung:

Überprüfen Sie die Dokumentklassifizierungsrichtlinie anhand von Organisationsregeln.

Ausgabe:

• CaptureInRecall: RestrictionEnforcement_Block
• SensitivityLabelDescription.Name: "Vertraulich - Nicht erfassen"

Beispielabfrageszenario 2: Webbrowser auf öffentlicher Website

Eingabe:

• Prozess: msedge.exe
• Fenster: news.example.com

Ihre Verarbeitung:

Überprüfen Sie die Domäne anhand der genehmigten Liste.

Ausgabe:

• CaptureInRecall: RestrictionEnforcement_Allow

Beispielabfrageszenario 3: Finanzanwendung

Eingabe:

• Prozess: FinanceApp.exe
• Benutzer: finance_user

Ihre Verarbeitung:

Überprüfen Sie die Vertraulichkeit von Benutzergruppen und Anwendungen.

Ausgabe:

• CaptureInRecall: RestrictionEnforcement_AuditAndAllow
• SensitivityLabelDescription.Name: "Finanzdaten - geprüft"

Implementierungsrichtlinien

Überlegungen zur Leistung

• Batchverarbeitung: Windows sendet möglicherweise mehrere Abfragen gleichzeitig, um effizienter zu sein. Optimieren Sie Ihren Code, um die Batchverarbeitung zu verarbeiten.
• Zwischenspeichern: Cacherichtlinienentscheidungen, wenn dies geeignet ist, um die Reaktionszeiten zu verbessern. Verwenden Sie die FlushEnterpriseContext Funktion zum Verwalten des Cachelebenszyklus.
• Asynchrone Vorgänge: Vermeiden Sie Blockierungsvorgänge in der Abfragefunktion. Kehren Sie schnell zurück, um auswirkungen auf die Benutzererfahrung zu verhindern.

Fehlerbehandlung

• Gibt geeignete HRESULT Codes für unterschiedliche Fehlerbedingungen zurück.
• Verwenden Sie die FlushEnterpriseContext Funktion, um Ressourcen zu bereinigen.
• Behandeln Sie Fälle, in denen Richtlinieninformationen vorübergehend nicht ordnungsgemäß verfügbar sind (standardmäßiges sicheres Verhalten).

Sicherheitsanforderungen

• In-Process Ausführung: Ihre DLL wird innerhalb des AIContext.exe Prozesses mit erhöhten Rechten ausgeführt.
• Sichere Codierungsmethoden: Befolgen Sie sichere Codierungsmethoden für die Speicherverwaltung. Überprüfen Sie alle Eingabeparameter gründlich.
• Digitale Signatur: Ihre DLL muss für die Bereitstellung authenticode signiert sein. Nicht signierte Binärdateien werden nicht geladen.
• Registrierungsschutz: Härtung des in der Gruppenrichtlinie angegebenen Registrierungsschlüssels, um nicht autorisierte Änderungen zu verhindern.

Ladevorgang

Recall verwendet LoadLibraryEx , um die DLL aus dem pfad zu laden, der in der Registrierung angegeben ist, und ruft dann auf GetProcAddress , um die Adressen der erforderlichen exportierten Funktionen abzurufen. Nach dem Aufrufen QueryEnterpriseContextRecall werden Daten aus der Antwort untersucht und kopiert, und rufen Sie dann aufFlushEnterpriseContext, damit Ihr Anbieter zugeordnete Ressourcen freigeben kann.

Get started

Führen Sie die folgenden Schritte aus, um Ihren DLP Anbieter zu erstellen und bereitzustellen:

1. Entwickeln Sie Ihre DLL , indem Sie die erforderlichen Exporte implementieren:

   • EnterpriseContextProvider_QueryEnterpriseContext
   • EnterpriseContextProvider_FlushEnterpriseContext

2. Testen Sie Ihre Implementierung mit Beispielabfragen, um das richtige Verhalten in verschiedenen Szenarien sicherzustellen.

3. Signieren Sie Ihre Binärdatei mit einem Authenticode-Zertifikat.

4. Erstellen Sie einen Installationsprozess, der :

   • Installiert Ihre DLL an einem sicheren Speicherort.
   • Richtet den Registrierungseintrag mit entsprechenden ACLs ein
   • Stellt Konfigurationstools für Administratoren bereit.

5. Stellen Sie Gruppenrichtlinienanweisungen für Administratoren bereit, um die SetDataLossPreventionProvider Richtlinie zu konfigurieren.

6. Bereitstellen und Konfigurieren in Ihrer Unternehmensumgebung.

Verwandte Links

• Verwalten Recall für Windows-Clients
• Richtlinie für den Anbieter für die Verhinderung von Datenverlust festlegen
• Schadensverhütung für Microsoft Purview Daten