Recall DLP Rozhraní API zprostředkovatele

Recall (Preview) umožňuje uživatelům vyhledávat místně uložené a analyzované snímky obrazovky pomocí přirozeného jazyka. Recall integruje se zprostředkovateli ochrany před únikem informací,DLP aby se zabránilo ukládání citlivého obsahu na základě zásad organizace. Tento článek popisuje veřejné rozhraní API, které umožňuje Recall pracovat s libovolným DLP nástrojem.

Architektura systému

Následující diagram znázorňuje interakci Windows Recall s vaším DLP poskytovatelem:

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

Veřejné rozhraní API

Základní struktury

RestrictionEnforcement – výčet

Definuje úroveň vynucení pro konkrétní omezení.

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

Hodnoty:

RestrictionEnforcement_Allow (0): Operace je povolená bez omezení.
RestrictionEnforcement_AuditAndAllow (1): Operace je povolená, ale měla by být protokolována pro účely auditu.
RestrictionEnforcement_Warn (2): Operace před pokračováním vyzve uživatele s upozorněním.
RestrictionEnforcement_Block (3): Operace je zcela zabráněna.

Struktura omezení

Určuje úroveň vynucení pro různé operace.

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

Členové:

CopyToClipboard: Úroveň vynucení pro kopírování obsahu do schránky.
CaptureInRecall: Úroveň vynucení pro zachycení obsahu ve Recall snímcích

SensitivityLabelDescription – struktura

Poskytuje informace o popisku citlivosti pro zobrazení uživateli.

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

Členové:

Název: Zobrazovaný název popisku citlivosti (například Důvěrné).
Barva: Šestnáctkový kód barvy pro vizuální reprezentaci (například "#FF0000").
TooltipText: Popisný text zobrazený, když uživatel najede myší na popisek.
Citlivost: Úroveň citlivosti čísel (vyšší hodnoty označují větší citlivost).

EnterpriseContextQuery – struktura

Obsahuje informace o požadavku na zachytávání a odpovědi od DLP poskytovatele.

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

Členové:

ProcessId: ID procesu aplikace, která se má zachytit.
WindowHandle: Úchyt pro zachycené okno.
FileName: Úplná cesta k souboru otevřenému v aplikaci (pokud je k dispozici).
SensitivityLabelId: Identifikátor jakéhokoli existujícího popisku citlivosti.
OrganizationId: Identifikátor organizace z aktuálního kontextu uživatele.
SensitivityLabelDescription: Informace popisku citlivosti, které se mají zobrazit (naplněné poskytovatelem).
Omezení: Vynucení omezení zachytávání (naplněná poskytovatelem)

Poznámka:

Aplikace můžou prostřednictvím rozhraní API poskytovat informace o popisku citlivosti UserActivity.ContentInfo . Podrobnosti o tom, jak by aplikace měly tyto informace formátovat a poskytovat, najdete v tématu Poskytnutí popisků citlivosti pro Recall obsah UserActivity ContentInfo.

Požadované exporty knihovny DLL

Knihovna DLP DLL zprostředkovatele musí exportovat tyto funkce s přesnými názvy:

EnterpriseContextProvider_QueryEnterpriseContext

Recall volá tuto funkci k vyhodnocení žádostí o zachytávání.

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

Parametry:

totalQuerySizeBytes: Celková velikost vyrovnávací paměti dotazu v bajtech.
queryBuffer: Ukazatel na pole EnterpriseContextQuery struktur. Váš poskytovatel by měl aktualizovat Restrictions pole a SensitivityLabelDescription pole na základě zásad organizace.

Návratová hodnota:

Vrátí S_OK úspěch nebo odpovídající HRESULT kód chyby při selhání.

Poznámky:

Systém Windows může současně odesílat více dotazů, aby byl efektivní. Vaše implementace by měla zpracovat všechny dotazy ve vyrovnávací paměti a před vrácením aktualizovat příslušná pole.

EnterpriseContextProvider_FlushEnterpriseContext

Recall volá tuto funkci pravidelně, aby poskytovatel mohl uvolnit řetězce nebo prostředky uložené v mezipaměti.

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

Poznámky:

Recall zavolá tuto funkci po prozkoumání nebo zkopírování dat z předchozí odpovědi dotazu. Pomocí této funkce můžete uvolnit všechny prostředky, vymazat mezipaměti nebo provádět operace čištění.

Registrace poskytovatele

Nastavení registru (zprostředkovatel)

Instalace DLP zprostředkovatele vytvoří položku registru, která obsahuje cestu k vaší knihovně DLL:

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

Aspekty zabezpečení:

Posílením klíče registru zabráníte neoprávněným úpravám. Nastavte příslušné seznamy ACL tak, aby omezovaly přístup k zápisu jenom správcům.

Konfigurace zásad skupiny (správce)

Správci nakonfigurují vašeho poskytovatele prostřednictvím zásad skupiny Nastavit poskytovatele ochrany před únikem informací :

Název zásady: SetDataLossPreventionProvider
Umístění zásad: Součásti >> Windows AI pro správu konfigurace > počítače
Formát hodnoty zásad: key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

Důležitý: Pole value odkazuje na název hodnoty registru pod klíčem registru určeným key.

Příklad konfigurace:

Pokud vytvoříte položku registru pomocí:

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

A vaše knihovna DLL má název YourCompanyDLP.dll, hodnota Zásad skupiny je:

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

Volitelná kontrola verzí:

Pro svého DLP poskytovatele můžete zadat minimální požadovanou verzi:

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

Pokud zadáte minversion, načte binární soubor pouze v případě, Recall že jeho verze je rovna nebo větší než zadaná verze.

Tok zpracování dotazů

Typická sekvence interakce

Windows Recall připraví k zachycení obsahu z okna aplikace.
Recall vytváří dotazy , které zahrnují:
- ID procesu a popisovač okna cílové aplikace
- Cesta k souboru (pokud má aplikace otevřený dokument)
- Všechny existující informace o popisku citlivosti
- ID organizace z kontextu aktuálního uživatele
Tvůj DLP Zprostředkovatel vyhodnocuje každý dotaz na zásady organizace:
- Zkontrolujte, jestli se má aplikace zachytit.
- Ověření omezení na úrovni souboru
- Vyhodnocení popisků citlivosti
- Použití zásad specifických pro uživatele nebo skupiny
Váš zprostředkovatel vrátí aktualizované struktury dotazů pomocí:
- Restrictions.CaptureInRecall: Povolení, upozornění, auditování nebo blokování zachytávání
- SensitivityLabelDescription: Název popisku, barva a popis pro zobrazení
- Všechny další důležité informace o omezení
Systém Windows Recall vynucuje vrácená omezení:
- Povolit: Zachytávání normálně
- AuditAndAllow: Zachytává a protokoluje akci.
- Upozornění: Před zachycením vyzve uživatele.
- Blok: Brání zachytávání zcela

Ukázkový scénář dotazu 1: Dokument wordu s popiskem Důvěrné

Vstup:

Proces: winword.exe
Soubor: SecretProject.docx
Označit: Confidential

Vaše zpracování:

Zkontrolujte zásady klasifikace dokumentů proti pravidlům organizace.

Výstup:

CaptureInRecall: RestrictionEnforcement_Block
SensitivityLabelDescription.Name: Důvěrné – Nezachytávat

Ukázkový scénář dotazu 2: Webový prohlížeč na veřejném webu

Vstup:

Proces: msedge.exe
Okno: news.example.com

Vaše zpracování:

Zkontrolujte doménu proti schválenému seznamu.

Výstup:

CaptureInRecall: RestrictionEnforcement_Allow

Ukázkový scénář dotazu 3: Finanční aplikace

Vstup:

Proces: FinanceApp.exe
Uživatel: finance_user

Vaše zpracování:

Zkontrolujte citlivost skupin uživatelů a aplikací.

Výstup:

CaptureInRecall: RestrictionEnforcement_AuditAndAllow
SensitivityLabelDescription.Name: Finance Data – Auditováno

Pokyny k implementaci

Důležité informace o výkonu

Dávkové zpracování: Systém Windows může současně odesílat více dotazů, aby byl efektivnější. Optimalizujte kód pro zpracování dávkového zpracování.
Ukládání do mezipaměti: Rozhodnutí o zásadách mezipaměti, pokud je to vhodné ke zlepšení doby odezvy. FlushEnterpriseContext Pomocí funkce můžete spravovat životní cyklus mezipaměti.
Asynchronní operace: Vyhněte se blokování operací ve funkci dotazu. Rychle se vraťte, abyste zabránili ovlivnění uživatelského prostředí.

Zpracování chyb

Vrátí odpovídající HRESULT kódy pro různé chybové podmínky.
FlushEnterpriseContext Pomocí funkce vyčistěte prostředky.
Zpracujte případy, kdy jsou informace o zásadách dočasně nedostupné (ve výchozím nastavení je bezpečné chování).

Požadavky na zabezpečení

In-Process spuštění: Knihovna DLL běží v procesu AIContext.exe se zvýšenými oprávněními.
Postupy zabezpečeného kódování: Dodržujte postupy zabezpečeného kódování pro správu paměti. Důkladně ověřte všechny vstupní parametry.
Digitální podepisování: Vaše knihovna DLL musí být pro nasazení podepsaná službou Authenticode. Nenačtou se nepodepsané binární soubory.
Ochrana registru: Posílení klíče registru zadaného v zásadách skupiny, aby se zabránilo neoprávněným úpravám.

Proces načítání

Recall používá LoadLibraryEx k načtení knihovny DLL z cesty zadané v registru a volání GetProcAddress pro načtení adres požadovaných exportovaných funkcí. Po volání QueryEnterpriseContextzkontroluje Recall a zkopíruje data z odpovědi a pak zavolá, FlushEnterpriseContext aby poskytovatel mohl uvolnit přidělené prostředky.

Začínáme

Pomocí následujícího postupu vytvořte a nasaďte svého DLP poskytovatele:

Vyvíjejte knihovnu DLL implementací požadovaných exportů:
- EnterpriseContextProvider_QueryEnterpriseContext
- EnterpriseContextProvider_FlushEnterpriseContext
Otestujte implementaci pomocí ukázkových dotazů, abyste zajistili správné chování v různých scénářích.
Podepište binární soubor certifikátem Authenticode.
Vytvořte proces instalace , který:
- Nainstaluje knihovnu DLL do zabezpečeného umístění.
- Nastaví položku registru s příslušnými seznamy ACL.
- Poskytuje nástroje pro konfiguraci pro správce.
Zadejte pokyny k zásadám skupiny pro správce, aby zásady nakonfigurovali SetDataLossPreventionProvider .
Nasazení a konfigurace v podnikovém prostředí

Správa Recall pro klienty Windows
Nastavení zásad zprostředkovatele ochrany před únikem informací
Ochrana před únikem informací Microsoft Purview

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-12-02

Recall DLP Rozhraní API zprostředkovatele

Architektura systému

Veřejné rozhraní API

Základní struktury

RestrictionEnforcement – výčet

Struktura omezení

SensitivityLabelDescription – struktura

EnterpriseContextQuery – struktura

Požadované exporty knihovny DLL

EnterpriseContextProvider_QueryEnterpriseContext

EnterpriseContextProvider_FlushEnterpriseContext

Registrace poskytovatele

Nastavení registru (zprostředkovatel)

Konfigurace zásad skupiny (správce)

Tok zpracování dotazů

Typická sekvence interakce

Ukázkový scénář dotazu 1: Dokument wordu s popiskem Důvěrné

Ukázkový scénář dotazu 2: Webový prohlížeč na veřejném webu

Ukázkový scénář dotazu 3: Finanční aplikace

Pokyny k implementaci

Důležité informace o výkonu

Zpracování chyb

Požadavky na zabezpečení

Proces načítání

Začínáme

Související odkazy

Váš názor

Další materiály