Recall DLP API Penyedia

Recall (pratinjau) memungkinkan pengguna mencari rekam jepret layar yang disimpan dan dianalisis secara lokal dengan menggunakan bahasa alami. Recall terintegrasi dengan penyedia Pencegahan Kehilangan Data (DLP) untuk mencegah penyimpanan konten sensitif berdasarkan kebijakan organisasi. Artikel ini menjelaskan API publik yang memungkinkan Recall untuk bekerja dengan alat apa pun DLP .

Arsitektur sistem

Diagram berikut menunjukkan bagaimana Windows Recall berinteraksi dengan penyedia Anda DLP :

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

Struktur Inti

Enumerasi PembatasanPerlakuan

Menentukan tingkat penerapan untuk pembatasan tertentu.

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

Nilai:

RestrictionEnforcement_Allow (0): Operasi diizinkan tanpa batasan.
RestrictionEnforcement_AuditAndAllow (1): Operasi diizinkan, tetapi harus dicatat untuk tujuan audit.
RestrictionEnforcement_Warn (2): Operasi meminta pengguna dengan peringatan sebelum melanjutkan.
RestrictionEnforcement_Block (3): Operasi dicegah sepenuhnya.

Struktur Pembatasan

Menentukan tingkat penerapan untuk berbagai operasi.

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

Anggota:

CopyToClipboard: Tingkat penerapan untuk menyalin konten ke clipboard.
CaptureInRecall: Tingkat penegakan untuk menangkap konten dalam Recall rekam jepret.

Struktur SensitivityLabelDescription

Menyediakan informasi tentang label sensitivitas untuk ditampilkan kepada pengguna.

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

Anggota:

Nama: Nama tampilan label sensitivitas (misalnya, "Rahasia").
Warna: Kode warna hex untuk representasi visual (misalnya, "#FF0000").
TooltipText: Teks deskriptif ditampilkan saat pengguna mengarahkan kursor ke label.
Sensitivitas: Tingkat sensitivitas numerik (nilai yang lebih tinggi menunjukkan sensitivitas yang lebih besar).

Struktur EnterpriseContextQuery

Berisi informasi tentang permintaan pengambilan dan respons dari DLP penyedia.

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

Anggota:

ProcessId: ID proses aplikasi yang akan diambil.
WindowHandle: Tangani ke jendela yang diambil.
FileName: Jalur lengkap ke file yang terbuka di aplikasi (jika berlaku).
SensitivityLabelId: Pengidentifikasi label sensitivitas yang ada.
OrganizationId: Pengidentifikasi organisasi dari konteks pengguna saat ini.
SensitivityLabelDescription: Informasi label sensitivitas yang akan ditampilkan (diisi oleh penyedia).
Pembatasan: Menangkap pembatasan yang akan diberlakukan (diisi oleh penyedia).

Nota

Aplikasi dapat memberikan informasi label sensitivitas melalui UserActivity.ContentInfo API. Untuk detail tentang bagaimana aplikasi harus memformat dan menyediakan informasi ini, lihat Menyediakan label sensitivitas ke Recall dengan UserActivity ContentInfo.

Ekspor DLL yang diperlukan

DLL penyedia Anda DLP harus mengekspor fungsi-fungsi ini dengan nama yang tepat yang ditunjukkan:

EnterpriseContextProvider_QueryEnterpriseContext

Recall memanggil fungsi ini untuk mengevaluasi permintaan pengambilan.

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

Parameter:

totalQuerySizeBytes: Ukuran total buffer kueri dalam byte.
queryBuffer: Penunjuk ke array EnterpriseContextQuery struktur. Penyedia Anda harus memperbarui Restrictions bidang dan SensitivityLabelDescription berdasarkan kebijakan organisasi.

Nilai Pengembalian:

S_OK Mengembalikan keberhasilan, atau kode kesalahan yang sesuai HRESULT pada kegagalan.

Keterangan:

Windows mungkin mengirim beberapa kueri secara bersamaan untuk efisiensi. Implementasi Anda harus memproses semua kueri di buffer dan memperbarui bidang yang sesuai sebelum kembali.

EnterpriseContextProvider_FlushEnterpriseContext

Recall memanggil fungsi ini secara berkala untuk memungkinkan penyedia Anda mengosongkan string atau sumber daya yang di-cache.

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

Keterangan:

Recall memanggil fungsi ini setelah memeriksa atau menyalin data dari respons kueri sebelumnya. Gunakan fungsi ini untuk membatalkan alokasi sumber daya apa pun, menghapus cache, atau melakukan operasi pembersihan.

Pendaftaran penyedia

Penyiapan registri (Penyedia)

Penginstalan penyedia Anda DLP membuat entri registri yang berisi jalur ke DLL Anda:

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

Pertimbangan keamanan:

Perkuat kunci registri untuk mencegah modifikasi yang tidak sah. Atur ACL yang sesuai untuk membatasi akses tulis ke administrator saja.

Konfigurasi Kebijakan Grup (Administrator)

Administrator mengonfigurasi penyedia Anda melalui Kebijakan Atur Grup Penyedia Pencegahan Kehilangan Data :

Nama Kebijakan: SetDataLossPreventionProvider
Lokasi Kebijakan: Templat > Administratif Konfigurasi > Komputer Windows Komponen > Windows AI
Format Nilai Kebijakan: key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

Penting: Bidang value mengacu pada nama nilai registri di bawah kunci registri yang ditentukan oleh key.

Contoh Konfigurasi:

Jika Anda membuat entri registri dengan menggunakan:

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

Dan DLL Anda diberi nama YourCompanyDLP.dll, nilai Kebijakan Grup adalah:

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

Pemeriksaan Versi Opsional:

Anda dapat menentukan versi minimum yang diperlukan untuk penyedia Anda DLP :

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

Jika Anda menentukan minversion, Recall memuat biner Anda hanya jika versinya sama dengan atau lebih besar dari versi yang ditentukan.

Alur Pemrosesan Kueri

Urutan interaksi umum

Windows Recall bersiap untuk mengambil konten dari jendela aplikasi.
Recall membuat kueri yang mencakup:
- ID proses dan handel jendela aplikasi target
- Jalur file (jika aplikasi memiliki dokumen terbuka)
- Informasi label sensitivitas yang ada
- ID Organisasi dari konteks pengguna saat ini
Anda DLP Penyedia mengevaluasi setiap kueri terhadap kebijakan organisasi:
- Periksa apakah aplikasi harus diambil
- Memverifikasi pembatasan tingkat file
- Mengevaluasi label sensitivitas
- Menerapkan kebijakan khusus pengguna/grup
Penyedia Anda mengembalikan struktur kueri yang diperbarui dengan:
- Restrictions.CaptureInRecall: Apakah akan mengizinkan, memperingatkan, mengaudit, atau memblokir pengambilan
- SensitivityLabelDescription: Nama label, warna, dan tipsalat untuk tampilan
- Informasi pembatasan relevan lainnya
Windows Recall memberlakukan pembatasan yang dikembalikan:
- Izinkan: Menangkap secara normal
- AuditAndAllow: Mengambil dan mencatat tindakan
- Peringatan: Meminta pengguna sebelum mengambil
- Blokir: Mencegah pengambilan sepenuhnya

Contoh Skenario Kueri 1: Dokumen Word dengan Label "Rahasia"

Masukan:

Proses: winword.exe
Arsip: SecretProject.docx
Label: Confidential

Pemrosesan Anda:

Periksa kebijakan klasifikasi dokumen terhadap aturan organisasi.

Hasil:

CaptureInRecall: RestrictionEnforcement_Block
SensitivityLabelDescription.Name: "Rahasia - Jangan Tangkap"

Contoh Skenario Kueri 2: Browser Web di Situs Publik

Masukan:

Proses: msedge.exe
Jendela: news.example.com

Pemrosesan Anda:

Periksa domain terhadap daftar yang disetujui.

Hasil:

CaptureInRecall: RestrictionEnforcement_Allow

Contoh Skenario Kueri 3: Aplikasi Keuangan

Masukan:

Proses: FinanceApp.exe
Pengguna: finance_user

Pemrosesan Anda:

Periksa sensitivitas grup pengguna dan aplikasi.

Hasil:

CaptureInRecall: RestrictionEnforcement_AuditAndAllow
SensitivityLabelDescription.Name: "Data Keuangan - Diaudit"

Pedoman Implementasi

Pertimbangan Performa

Pemrosesan Batch: Windows mungkin mengirim beberapa kueri secara bersamaan agar lebih efisien. Optimalkan kode Anda untuk menangani pemrosesan batch.
Penembolokan: Keputusan kebijakan cache jika sesuai untuk meningkatkan waktu respons. FlushEnterpriseContext Gunakan fungsi untuk mengelola siklus hidup cache.
Operasi Asinkron: Hindari operasi pemblokiran dalam fungsi kueri. Kembali dengan cepat untuk mencegah berdampak pada pengalaman pengguna.

Penanganan Kesalahan

Mengembalikan kode yang sesuai HRESULT untuk kondisi kesalahan yang berbeda.
FlushEnterpriseContext Gunakan fungsi untuk membersihkan sumber daya.
Tangani kasus di mana informasi kebijakan sementara tidak tersedia dengan baik (default ke perilaku aman).

Persyaratan keamanan

In-Process eksekusi: DLL Anda berjalan dalam proses dalam proses AIContext.exe dengan hak istimewa yang ditingkatkan.
Praktik pengkodan yang aman: Ikuti praktik pengkodan yang aman untuk manajemen memori. Validasi semua parameter input secara menyeluruh.
Penandatanganan digital: DLL Anda harus ditandatangani Authenticode untuk penyebaran. Biner yang tidak ditandatangani tidak dimuat.
Perlindungan registri: Memperkuat kunci registri yang ditentukan dalam Kebijakan Grup untuk mencegah modifikasi yang tidak sah.

Proses pemuatan

Recall LoadLibraryEx menggunakan untuk memuat DLL Anda dari jalur yang ditentukan dalam registriGetProcAddress, lalu memanggil untuk mengambil alamat fungsi yang diekspor yang diperlukan. Setelah memanggil QueryEnterpriseContext, Recall memeriksa dan menyalin data dari respons, maka panggilan FlushEnterpriseContext untuk memungkinkan penyedia Anda untuk membebaskan sumber daya yang dialokasikan.

Get started

Ikuti langkah-langkah berikut untuk membuat dan menyebarkan penyedia Anda DLP :

Kembangkan DLL Anda dengan menerapkan ekspor yang diperlukan:
- EnterpriseContextProvider_QueryEnterpriseContext
- EnterpriseContextProvider_FlushEnterpriseContext
Uji implementasi Anda dengan kueri sampel untuk memastikan perilaku yang benar di berbagai skenario.
Tanda tangani biner Anda dengan sertifikat Authenticode.
Buat proses penginstalan yang:
- Menginstal DLL Anda ke lokasi yang aman
- Menyiapkan entri registri dengan ACL yang sesuai
- Menyediakan alat konfigurasi untuk administrator
Berikan instruksi Kebijakan Grup bagi administrator untuk mengonfigurasi SetDataLossPreventionProvider kebijakan.
Menyebarkan dan mengonfigurasi di lingkungan perusahaan Anda.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-02

Recall DLP API Penyedia

Arsitektur sistem

API Publik

Struktur Inti

Enumerasi PembatasanPerlakuan

Struktur Pembatasan

Struktur SensitivityLabelDescription

Struktur EnterpriseContextQuery

Ekspor DLL yang diperlukan

EnterpriseContextProvider_QueryEnterpriseContext

EnterpriseContextProvider_FlushEnterpriseContext

Pendaftaran penyedia

Penyiapan registri (Penyedia)

Konfigurasi Kebijakan Grup (Administrator)

Alur Pemrosesan Kueri

Urutan interaksi umum

Contoh Skenario Kueri 1: Dokumen Word dengan Label "Rahasia"

Contoh Skenario Kueri 2: Browser Web di Situs Publik

Contoh Skenario Kueri 3: Aplikasi Keuangan

Pedoman Implementasi

Pertimbangan Performa

Penanganan Kesalahan

Persyaratan keamanan

Proses pemuatan

Get started

Tautan Terkait

Saran dan Komentar

Sumber Daya Tambahan: