Recall DLP Provider-API

Recall (preview) stelt gebruikers in staat om lokaal opgeslagen en geanalyseerde momentopnamen van hun scherm te doorzoeken met behulp van natuurlijke taal. Recall kan worden geïntegreerd met providers voor preventie van gegevensverlies (DLP) om de opslag van gevoelige inhoud te voorkomen op basis van organisatiebeleid. In dit artikel wordt de openbare API beschreven waarmee u met elk Recall hulpprogramma kunt DLP werken.

Systeemarchitectuur

In het volgende diagram ziet u hoe Windows Recall communiceert met uw DLP provider:

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

Openbare API

Kernstructuren

Opsomming RestrictionEnforcement

Hiermee definieert u het afdwingingsniveau voor een specifieke beperking.

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

Waarden:

• RestrictionEnforcement_Allow (0): De bewerking is zonder beperkingen toegestaan.
• RestrictionEnforcement_AuditAndAllow (1): De bewerking is toegestaan, maar moet worden geregistreerd voor controledoeleinden.
• RestrictionEnforcement_Warn (2): De bewerking vraagt de gebruiker om een waarschuwing voordat u doorgaat.
• RestrictionEnforcement_Block (3): De bewerking wordt volledig voorkomen.

Structuur van beperkingen

Hiermee geeft u het afdwingingsniveau voor verschillende bewerkingen.

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

Leden:

• CopyToClipboard: afdwingingsniveau voor het kopiëren van inhoud naar het klembord.
• CaptureInRecall: afdwingingsniveau voor het vastleggen van inhoud in Recall momentopnamen.

SensitivityLabelDescription-structuur

Biedt informatie over een vertrouwelijkheidslabel voor weergave aan de gebruiker.

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

Leden:

• Naam: Weergavenaam van het vertrouwelijkheidslabel (bijvoorbeeld 'Vertrouwelijk').
• Kleur: Hex-kleurcode voor visuele weergave (bijvoorbeeld '#FF0000').
• TooltipText: beschrijvende tekst die wordt weergegeven wanneer de gebruiker de muisaanwijzer over het label beweegt.
• Gevoeligheid: numeriek vertrouwelijkheidsniveau (hogere waarden geven een grotere gevoeligheid aan).

EnterpriseContextQuery-structuur

Bevat informatie over een capture-aanvraag en het antwoord van de DLP provider.

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

Leden:

• ProcessId: proces-id van de toepassing die moet worden vastgelegd.
• WindowHandle: Greep naar het venster dat wordt vastgelegd.
• Bestandsnaam: volledig pad naar het bestand dat is geopend in de toepassing (indien van toepassing).
• SensitivityLabelId: Id van een bestaand vertrouwelijkheidslabel.
• OrganizationId: Organisatie-id uit de huidige gebruikerscontext.
• SensitivityLabelDescription: Informatie over vertrouwelijkheidslabels die moeten worden weergegeven (ingevuld door provider).
• Beperkingen: Vastleggen van beperkingen die moeten worden afgedwongen (ingevuld door provider).

Vereiste DLL-exports

Uw DLP provider-DLL moet deze functies exporteren met de exacte namen die worden weergegeven:

EnterpriseContextProvider_QueryEnterpriseContext

Recall roept deze functie aan om capture-aanvragen te evalueren.

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

Parameters:

• totalQuerySizeBytes: Totale grootte van de querybuffer in bytes.
• queryBuffer: Aanwijzer naar een matrix met EnterpriseContextQuery structuren. Uw provider moet de Restrictions en SensitivityLabelDescription velden bijwerken op basis van organisatiebeleid.

Retourwaarde:

• Retourneert S_OK een geslaagde fout of een geschikte HRESULT foutcode bij fouten.

Opmerkingen:

Windows kan meerdere query's tegelijk verzenden voor efficiëntie. Uw implementatie moet alle query's in de buffer verwerken en de juiste velden bijwerken voordat ze worden geretourneerd.

EnterpriseContextProvider_FlushEnterpriseContext

Recall roept deze functie periodiek aan om uw provider toe te staan om tekenreeksen of resources in de cache vrij te maken.

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

Opmerkingen:

Recall roept deze functie aan nadat deze gegevens uit een eerder queryantwoord heeft onderzocht of gekopieerd. Gebruik deze functie om de toewijzing van resources ongedaan te maken, caches te wissen of opschoonbewerkingen uit te voeren.

Providerregistratie

Registerinstallatie (provider)

De installatie van de DLP provider maakt een registervermelding die het pad naar uw DLL bevat:

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

Beveiligingsoverwegingen:

Behard de registersleutel om te voorkomen dat onbevoegden worden gewijzigd. Stel de juiste ACL's in om alleen schrijftoegang tot beheerders te beperken.

Configuratie van groepsbeleid (beheerder)

Beheerders configureren uw provider via groepsbeleid voor preventie van gegevensverlies instellen :

• Beleidsnaam: SetDataLossPreventionProvider
• Beleidslocatie: Computerconfiguratiebeheersjablonen >> Windows-onderdelen > Windows AI
• Notatie van beleidswaarde: key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

Belangrijk: Het value veld verwijst naar de naam van de registerwaarde onder de registersleutel die is opgegeven door key.

Voorbeeldconfiguratie:

Als u een registervermelding maakt met behulp van:

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

En uw DLL heeft de naam YourCompanyDLP.dll, de waarde groepsbeleid is:

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

Optionele versiecontrole:

U kunt een minimale vereiste versie voor uw DLP provider opgeven:

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

Als u een minversion, Recall laadt uw binaire bestand alleen als de versie gelijk is aan of groter is dan de opgegeven versie.

Queryverwerkingsstroom

Typische interactiereeks

1. Ramen Recall bereidt zich voor om inhoud van een toepassingsvenster vast te leggen.

2. Recall maakt query's met:

   • Proces-id en venstergreep van de doeltoepassing
   • Bestandspad (als de toepassing een geopend document heeft)
   • Alle bestaande informatie over vertrouwelijkheidslabels
   • Organisatie-id uit de huidige gebruikerscontext

3. Jouw DLP Provider evalueert elke query op basis van organisatiebeleid:

   • Controleer of de toepassing moet worden vastgelegd
   • Beperkingen op bestandsniveau controleren
   • Vertrouwelijkheidslabels evalueren
   • Gebruikers-/groepsspecifieke beleidsregels toepassen

4. Uw provider retourneert bijgewerkte querystructuren met:

   • Restrictions.CaptureInRecall: Of u vastleggen wilt toestaan, waarschuwen, controleren of blokkeren
   • SensitivityLabelDescription: Labelnaam, kleur en knopinfo voor weergave
   • Alle andere relevante beperkingsgegevens

5. Windows Recall dwingt de geretourneerde beperkingen af:

   • Toestaan: Captures normaal
   • AuditAndAllow: legt de actie vast en registreert
   • Waarschuwen: een gebruiker vragen voordat deze wordt vastgelegd
   • Blokkeren: Voorkomt dat vastleggen volledig wordt voorkomen

Voorbeeldqueryscenario 1: Word-document met vertrouwelijk label

Input:

• Proces: winword.exe
• Bestand: SecretProject.docx
• Etiket: Confidential

Uw verwerking:

Controleer het documentclassificatiebeleid op basis van organisatieregels.

Uitvoer:

• CaptureInRecall: RestrictionEnforcement_Block
• SensitivityLabelDescription.Name: "Vertrouwelijk - Niet vastleggen"

Voorbeeldqueryscenario 2: Webbrowser op openbare site

Input:

• Proces: msedge.exe
• Venster: news.example.com

Uw verwerking:

Controleer het domein op basis van de goedgekeurde lijst.

Uitvoer:

• CaptureInRecall: RestrictionEnforcement_Allow

Voorbeeldqueryscenario 3: Financiële toepassing

Input:

• Proces: FinanceApp.exe
• Gebruiker: finance_user

Uw verwerking:

Controleer de gevoeligheid van gebruikersgroepen en toepassingen.

Uitvoer:

• CaptureInRecall: RestrictionEnforcement_AuditAndAllow
• SensitivityLabelDescription.Name: "Financiële gegevens - Gecontroleerd"

Implementatierichtlijnen

Prestatieoverwegingen

• Batchverwerking: Windows kan meerdere query's tegelijk verzenden om efficiënter te zijn. Optimaliseer uw code om batchverwerking te verwerken.
• Caching: Beslissingen over cachebeleid indien van toepassing om de reactietijden te verbeteren. Gebruik de functie om de FlushEnterpriseContext levenscyclus van de cache te beheren.
• Asynchrone bewerkingen: voorkom blokkeringsbewerkingen in de queryfunctie. Ga snel terug om te voorkomen dat dit van invloed is op de gebruikerservaring.

Foutafhandeling

• Retourneer de juiste HRESULT codes voor verschillende foutvoorwaarden.
• Gebruik de FlushEnterpriseContext functie om resources op te schonen.
• Omgaan met gevallen waarin beleidsinformatie tijdelijk niet beschikbaar is (standaard op veilig gedrag).

Beveiligingsvereisten

• In-Process uitvoering: uw DLL wordt in uitvoering uitgevoerd binnen het AIContext.exe proces met verhoogde bevoegdheden.
• Beveiligingscoderingsprocedures: volg beveiligingscoderingsprocedures voor geheugenbeheer. Valideer alle invoerparameters grondig.
• Digitale ondertekening: uw DLL moet authenticode zijn ondertekend voor implementatie. Niet-ondertekende binaire bestanden worden niet geladen.
• Registerbeveiliging: behard de registersleutel die is opgegeven in Groepsbeleid om onbevoegde wijzigingen te voorkomen.

Laadproces

Recall gebruikt LoadLibraryEx voor het laden van uw DLL vanuit het pad dat is opgegeven in het register en roept vervolgens GetProcAddress aan om de adressen van de vereiste geëxporteerde functies op te halen. Na het aanroepen QueryEnterpriseContextworden Recall gegevens uit het antwoord onderzocht en gekopieerd en vervolgens aangeroepen FlushEnterpriseContext om uw provider toe te staan om toegewezen resources vrij te maken.

Get started

Volg deze stappen om uw DLP provider te maken en te implementeren:

1. Ontwikkel uw DLL door de vereiste exports te implementeren:

   • EnterpriseContextProvider_QueryEnterpriseContext
   • EnterpriseContextProvider_FlushEnterpriseContext

2. Test uw implementatie met voorbeeldquery's om het juiste gedrag in verschillende scenario's te garanderen.

3. Onderteken uw binaire bestand met een Authenticode-certificaat.

4. Installatieproces maken dat:

   • Installeert uw DLL op een veilige locatie
   • Hiermee stelt u de registervermelding in met de juiste ACL's
   • Biedt configuratiehulpprogramma's voor beheerders

5. Geef instructies voor groepsbeleid op voor beheerders om het SetDataLossPreventionProvider beleid te configureren.

6. Implementeren en configureren in uw bedrijfsomgeving.

Verwante koppelingen

• Beheren Recall voor Windows-clients
• Beleid voor preventie van gegevensverlies instellen
• Microsoft Purview-preventie van gegevensverlies