Recall DLP 공급자 API

Recall (미리 보기)를 사용하면 자연어를 사용하여 로컬로 저장되고 분석된 화면의 스냅샷을 검색할 수 있습니다. Recall 는 조직 정책에 따라 중요한 콘텐츠의 스토리지를 방지하기 위해 데이터 손실 방지(DLP) 공급자와 통합됩니다. 이 문서에서는 모든 Recall 도구를 사용할 수 있는 공용 API에 대해 설명합니다DLP.

시스템 아키텍처

다음 다이어그램에서는 Windows Recall 가 공급자와 상호 작용하는 방법을 보여 줍니다 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

핵심 구조체

RestrictionEnforcement 열거형

특정 제한에 대한 적용 수준을 정의합니다.

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

값:

• RestrictionEnforcement_Allow (0): 제한 없이 작업이 허용됩니다.
• RestrictionEnforcement_AuditAndAllow (1): 작업이 허용되지만 감사 목적으로 기록해야 합니다.
• RestrictionEnforcement_Warn (2): 계속하기 전에 사용자에게 경고를 표시합니다.
• RestrictionEnforcement_Block (3): 작업이 완전히 방지됩니다.

제한 구조체

다양한 작업에 대한 적용 수준을 지정합니다.

struct Restrictions
{
    RestrictionEnforcement CopyToClipboard;
    RestrictionEnforcement CaptureInRecall;
};

회원:

• CopyToClipboard: 콘텐츠를 클립보드에 복사하기 위한 적용 수준입니다.
• CaptureInRecall: 스냅샷에서 Recall 콘텐츠를 캡처하기 위한 적용 수준입니다.

SensitivityLabelDescription 구조체

사용자에게 표시할 민감도 레이블에 대한 정보를 제공합니다.

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

회원:

• 이름: 민감도 레이블의 표시 이름(예: "기밀").
• 색: 시각적 표현을 위한 16진수 색 코드(예: "#FF0000").
• TooltipText: 사용자가 레이블을 마우스로 가리킬 때 표시되는 설명 텍스트입니다.
• 민감도: 숫자 민감도 수준(값이 높을수록 민감도가 높음).

EnterpriseContextQuery 구조체

캡처 요청 및 공급자의 응답 DLP 에 대한 정보를 포함합니다.

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

회원:

• ProcessId: 캡처할 애플리케이션의 프로세스 ID입니다.
• WindowHandle: 캡처되는 창에 대한 핸들입니다.
• FileName: 애플리케이션에서 열려 있는 파일의 전체 경로입니다(해당하는 경우).
• SensitivityLabelId: 기존 민감도 레이블의 식별자입니다.
• OrganizationId: 현재 사용자 컨텍스트의 조직 식별자입니다.
• SensitivityLabelDescription: 표시할 민감도 레이블 정보(공급자에 의해 채워집니다).
• 제한 사항: 적용할 캡처 제한(공급자에 의해 채워집니다).

필요한 DLL 내보내기

DLP 공급자 DLL은 다음과 같은 정확한 이름을 사용하여 이러한 함수를 내보내야 합니다.

EnterpriseContextProvider_QueryEnterpriseContext

Recall 는 캡처 요청을 평가하기 위해 이 함수를 호출합니다.

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

매개 변수:

• totalQuerySizeBytes: 쿼리 버퍼의 총 크기(바이트)입니다.
• queryBuffer: 구조체 EnterpriseContextQuery 배열에 대한 포인터입니다. 공급자는 Restrictions 조직 정책에 따라 필드와 SensitivityLabelDescription 필드를 업데이트해야 합니다.

반환 값:

• 성공 또는 실패에 대한 적절한 S_OK 오류 코드를 반환 HRESULT 합니다.

설명:

Windows는 효율성을 위해 동시에 여러 쿼리를 보낼 수 있습니다. 구현은 버퍼의 모든 쿼리를 처리하고 반환하기 전에 적절한 필드를 업데이트해야 합니다.

EnterpriseContextProvider_FlushEnterpriseContext

Recall 는 공급자가 캐시된 문자열 또는 리소스를 해제할 수 있도록 주기적으로 이 함수를 호출합니다.

VOID STDMETHODCALLTYPE EnterpriseContextProvider_FlushEnterpriseContext();

설명:

Recall 는 이전 쿼리 응답에서 데이터를 검사하거나 복사한 후 이 함수를 호출합니다. 이 함수를 사용하여 리소스의 할당을 취소하거나, 캐시를 지우거나, 정리 작업을 수행합니다.

공급자 등록

레지스트리 설정(공급자)

DLP 공급자 설치 시 DLL에 대한 경로가 포함된 레지스트리 항목이 만들어집니다.

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

보안 고려 사항:

레지스트리 키를 강화하여 무단 수정을 방지합니다. 관리자에 대한 쓰기 액세스만 제한하도록 적절한 ACL을 설정합니다.

그룹 정책 구성(관리자)

관리자는 데이터 손실 방지 공급자 그룹 정책 설정을 통해 공급자를 구성합니다.

• 정책 이름: SetDataLossPreventionProvider
• 정책 위치: 컴퓨터 구성 > 관리 템플릿 > Windows 구성 요소 > Windows AI
• 정책 값 형식: key:<REGISTRY_PATH>; value:<VALUE_NAME>; binary:<DLL_NAME>

중요하다:value 필드는 에 지정된 key레지스트리 키 아래의 레지스트리 값 이름을 참조합니다.

구성 예제:

다음을 사용하여 레지스트리 항목을 만드는 경우:

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

DLL 이름이 지정 YourCompanyDLP.dll되고 그룹 정책 값은 다음과 같습니다.

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

선택적 버전 검사:

공급자에 필요한 최소 버전을 지정할 수 있습니다 DLP .

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

지정하는 minversionRecall 경우 해당 버전이 지정된 버전과 같거나 큰 경우에만 이진 파일을 로드합니다.

쿼리 처리 흐름

일반적인 상호 작용 시퀀스

1. Windows Recall 는 애플리케이션 창에서 콘텐츠를 캡처하도록 준비합니다.

2. Recall 는 다음을 포함하는 쿼리를 만듭니다.

   • 대상 애플리케이션의 프로세스 ID 및 창 핸들
   • 파일 경로(애플리케이션에 열려 있는 문서가 있는 경우)
   • 기존 민감도 레이블 정보
   • 현재 사용자 컨텍스트의 조직 ID

3. 당신의 DLP 공급자는 조직 정책에 대해 각 쿼리를 평가합니다.

   • 애플리케이션을 캡처해야 하는지 확인
   • 파일 수준 제한 확인
   • 민감도 레이블 평가
   • 사용자/그룹별 정책 적용

4. 공급자는 다음을 사용하여 업데이트된 쿼리 구조를 반환합니다.

   • Restrictions.CaptureInRecall: 캡처를 허용, 경고, 감사 또는 차단할지 여부
   • SensitivityLabelDescription: 표시할 레이블 이름, 색 및 도구 설명
   • 기타 관련 제한 정보

5. Windows Recall 는 반환된 제한을 적용 합니다.

   • 허용: 일반적으로 캡처
   • AuditAndAllow: 작업을 캡처하고 기록합니다.
   • 경고: 캡처하기 전에 사용자에게 프롬프트 표시
   • 블록: 완전히 캡처 방지

예제 쿼리 시나리오 1: "기밀" 레이블이 있는 Word 문서

입력:

• 프로세스: winword.exe
• 파일: SecretProject.docx
• 레이블: Confidential

처리 중:

조직 규칙에 대한 문서 분류 정책을 확인합니다.

출력:

• CaptureInRecall: RestrictionEnforcement_Block
• SensitivityLabelDescription.Name: "기밀 - 캡처 안 함"

예제 쿼리 시나리오 2: 공용 사이트의 웹 브라우저

입력:

• 프로세스: msedge.exe
• 창: news.example.com

처리 중:

승인된 목록에 대해 도메인을 확인합니다.

출력:

• CaptureInRecall: RestrictionEnforcement_Allow

예제 쿼리 시나리오 3: Finance Application

입력:

• 프로세스: FinanceApp.exe
• 사용자: finance_user

처리 중:

사용자 그룹 및 애플리케이션 민감도를 확인합니다.

출력:

• CaptureInRecall: RestrictionEnforcement_AuditAndAllow
• SensitivityLabelDescription.Name: "재무 데이터 - 감사됨"

구현 지침

성능 고려 사항

• 일괄 처리: Windows에서 더 효율적으로 여러 쿼리를 동시에 보낼 수 있습니다. 일괄 처리를 처리하도록 코드를 최적화합니다.
• 캐싱: 응답 시간을 개선하기 위해 적절한 경우 정책 결정을 캐시합니다. 이 함수를 FlushEnterpriseContext 사용하여 캐시 수명 주기를 관리합니다.
• 비동기 작업: 쿼리 함수에서 작업을 차단하지 않습니다. 사용자 환경에 영향을 주지 않도록 신속하게 반환합니다.

오류 처리

• 다른 오류 조건에 대한 적절한 HRESULT 코드를 반환합니다.
• 함수를 FlushEnterpriseContext 사용하여 리소스를 정리합니다.
• 정책 정보를 일시적으로 사용할 수 없는 경우를 처리합니다(기본값: 안전한 동작).

보안 요구 사항

• In-Process 실행: DLL은 상승된 권한으로 AIContext.exe 프로세스 내에서 in-process로 실행됩니다.
• 보안 코딩 사례: 메모리 관리에 대한 보안 코딩 사례를 따릅니다. 모든 입력 매개 변수의 유효성을 철저히 검사합니다.
• 디지털 서명: DLL은 배포를 위해 Authenticode로 서명되어야 합니다. 서명되지 않은 이진 파일은 로드되지 않습니다.
• 레지스트리 보호: 그룹 정책에 지정된 레지스트리 키를 강화하여 무단 수정을 방지합니다.

로드 프로세스

Recall 에서는 LoadLibraryEx 레지스트리에 지정된 경로에서 DLL을 로드한 다음, 내보낸 필수 함수의 주소를 검색하기 위해 호출 GetProcAddress 합니다. 호출 QueryEnterpriseContextRecall 한 후 응답에서 데이터를 검사하고 복사한 다음 공급자가 할당된 리소스를 해제할 수 있도록 호출 FlushEnterpriseContext 합니다.

시작하기

다음 단계에 따라 공급자를 만들고 배포합니다 DLP .

1. 필요한 내보내기를 구현하여 DLL을 개발합니다.

   • EnterpriseContextProvider_QueryEnterpriseContext
   • EnterpriseContextProvider_FlushEnterpriseContext

2. 샘플 쿼리를 사용하여 구현을 테스트하여 다양한 시나리오에서 올바른 동작을 확인합니다.

3. Authenticode 인증서를 사용하여 이진 파일에 서명합니다.

4. 다음과 같은 설치 프로세스를 만듭니다.

   • 보안 위치에 DLL 설치
   • 적절한 ACL을 사용하여 레지스트리 항목 설정
   • 관리자를 위한 구성 도구 제공

5. 관리자가 정책을 구성할 SetDataLossPreventionProvider 수 있도록 그룹 정책 지침을 제공합니다.

6. 엔터프라이즈 환경에서 배포하고 구성합니다.

관련 링크

• Windows 클라이언트용 관리 Recall
• 데이터 손실 방지 공급자 정책 설정
• Microsoft Purview 데이터 손실 방지