PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET 콜백 함수(wincrypt.h)

아티클
03/03/2024

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET 콜백 함수는 개체를 검색합니다. 사용자 지정 공급자의 일부로 이 함수를 구현해야 합니다. 이 함수는 현재 보안 채널(Schannel) 보안 패키지에서만 호출됩니다.

구문

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET PfnCryptObjectLocatorProviderGet;

BOOL PfnCryptObjectLocatorProviderGet(
  [in, optional] LPVOID pPluginContext,
  [in, optional] PCRYPT_DATA_BLOB pIdentifier,
  [in]           DWORD dwNameType,
  [in]           PCERT_NAME_BLOB pNameBlob,
  [out]          PBYTE *ppbContent,
  [out]          DWORD *pcbContent,
  [out]          PCWSTR *ppwszPassword,
  [out]          PCRYPT_DATA_BLOB *ppIdentifier
)
{...}

매개 변수

[in, optional] pPluginContext

이 공급자가 정의하고 PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE 함수에서 반환하는 선택적 버퍼에 대한 포인터입니다. 버퍼는 호출자에 의해 수정되지 않습니다. 공급자는 데이터를 사용하여 수행할 작업을 결정하거나 추가 정보를 유지 관리할 수 있습니다.

[in, optional] pIdentifier

개체 식별자를 포함하는 CRYPTOAPI_BLOB 구조체에 대한 포인터입니다. 이 함수에 대한 첫 번째 호출에서 이 값은 항상 NULL 이어야 합니다.

[in] dwNameType

pNameBlob 매개 변수의 이름 형식입니다. 가능한 값은 다음과 같습니다. 이 함수의 구현은 Schannel에 의해 전달되는 CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE 처리할 수 있어야 합니다.

CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE(1(0x1))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_NAME_TYPE(32(0x20))

CRYPT_OBJECT_LOCATOR_FIRST_RESERVED_USER_NAME_TYPE(33(0x21))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_USER_NAME_TYPE(0x0000FFFF)

[in] pNameBlob

호출하는 애플리케이션이 개체를 고유하게 식별하는 데 사용하는 이름을 포함하는 CRYPTOAPI_BLOB 구조체에 대한 포인터입니다. 공급자는 이 이름을 사용하여 요청된 개체를 찾습니다. Schannel은 현재 IDN 이름이 punycode에서 변환된 UTF8로 인코딩된 DNS(도메인 이름 시스템) 호스트 이름을 제출합니다.

[out] ppbContent

반환할 개체가 포함된 바이트 배열에 대한 포인터입니다.

[out] pcbContent

ppbContent 매개 변수가 가리키는 개체의 크기(바이트)입니다.

[out] ppwszPassword

개체를 암호화하는 데 사용되는 암호(있는 경우)를 포함하는 Null로 끝나는 유니코드 문자열입니다. 개체가 PFX(개인 정보 교환) 파일인 경우 암호는 일반적으로 암호화를 수행하는 데 사용됩니다. 암호가 필요하지 않은 경우 이 값은 NULL 일 수 있습니다.

[out] ppIdentifier

이 함수에 대한 후속 호출 및 변경 알림에 사용할 수 있는 선택적 식별자에 대한 포인터를 수신하는 주소입니다. 자세한 내용은 설명 부분을 참조하세요. 공급자가 이 값을 NULL로 설정하면 Schannel은 내부적으로 pNameBlob 매개 변수 값을 사용합니다.

반환 값

함수가 성공하면 0이 아닌 값(TRUE)을 반환합니다.

함수가 실패하면 0(FALSE)을 반환하고 SetLastError 함수에 적절한 오류를 지정합니다. 대부분의 오류는 Schannel을 통해 변경되지 않고 전달되지만 이 동작은 보장되지 않습니다. 일부 오류는 다른 오류에 매핑될 수 있습니다.

지정된 DNS 이름(pNameBlob) 또는 식별자(pIdentifier)에 대해 개체를 반환할 수 없는 경우 FALSE를 반환하고 SetLastError 함수에서 CRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUND 지정합니다.

설명

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET 콜백 함수는 현재 보안 채널(Schannel) 보안 패키지에서만 호출됩니다. 다음 중 하나를 캡슐화하는 개체를 반환할 수 있습니다.

PFX(개인 정보 교환) 바이트 배열
인증서 저장소입니다.
제네릭 BLOB입니다. 이는 현재 Schannel에서 지원되지 않습니다.

이 함수가 처음 호출되면 Schannel은 pNameBlob 인수에 DNS 호스트 이름을 제출하여 개체가 의도된 호스트를 지정합니다. 공급자는 이름을 처리(와일드카드 일치, 파일 경로 빌드 등)하여 찾을 개체를 결정해야 합니다.

많은 호스트 이름을 하나의 개체에 매핑할 수 있으므로 공급자는 ppIdentifier 매개 변수를 사용하여 CAPI(암호화 API) 함수의 후속 호출에 사용할 수 있는 내부적으로 정의된 식별자를 공급자에게 반환할 수 있습니다. 그런 다음 공급자는 식별자를 사용하여 적절한 개체를 찾는 데 도움을 줄 수 있습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2012 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	wincrypt.h

추가 정보

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE

다음을 통해 공유