CryptAcquireCertificatePrivateKey 함수(wincrypt.h)
CryptAcquireCertificatePrivateKey 함수는 인증서에 대한 프라이빗 키를 가져옵니다. 이 함수는 사용자의 인증서를 사용할 수 있지만 사용자 키 컨테이너의 핸들을 사용할 수 없는 경우 사용자의 프라이빗 키 에 대한 액세스를 가져오는 데 사용됩니다. 이 함수는 다른 사용자가 아닌 프라이빗 키의 소유자만 사용할 수 있습니다.
CSP 핸들과 사용자의 프라이빗 키가 포함된 키 컨테이너를 사용할 수 있는 경우 CryptGetUserKey 함수를 대신 사용해야 합니다.
BOOL CryptAcquireCertificatePrivateKey(
[in] PCCERT_CONTEXT pCert,
[in] DWORD dwFlags,
[in, optional] void *pvParameters,
[out] HCRYPTPROV_OR_NCRYPT_KEY_HANDLE *phCryptProvOrNCryptKey,
[out] DWORD *pdwKeySpec,
[out] BOOL *pfCallerFreeProvOrNCryptKey
);
[in] pCert
프라이빗 키를 가져올 인증서 컨텍스트를 포함하는 CERT_CONTEXT 구조체의 주소입니다.
[in] dwFlags
이 함수의 동작을 수정하는 플래그 집합입니다. 이 값은 0이거나 다음 값 중 하나 이상의 조합일 수 있습니다.
값 | 의미 |
---|---|
|
핸들을 이미 획득하고 캐시한 경우 동일한 핸들이 반환됩니다. 그렇지 않으면 인증서의 CERT_KEY_CONTEXT_PROP_ID 속성을 사용하여 새 핸들을 가져오고 캐시합니다.
이 플래그가 설정되면 pfCallerFreeProvOrNCryptKey 매개 변수는 FALSE 를 수신하고 호출 애플리케이션은 핸들을 해제하지 않아야 합니다. 인증서 컨텍스트가 해제되면 핸들이 해제됩니다. 그러나 키가 사용 중인 한 pCert 매개 변수에서 참조하는 인증서 컨텍스트를 유지해야 합니다. 그렇지 않으면 키를 사용하는 작업이 실패합니다. |
|
인증서의 공개 키 는 CSP( 암호화 서비스 공급자 )가 반환한 공개 키와 비교됩니다. 키가 일치하지 않으면 획득 작업이 실패하고 마지막 오류 코드가 NTE_BAD_PUBLIC_KEY 설정됩니다. 캐시된 핸들이 반환되면 비교가 이루어지지 않습니다. |
|
이 속성을 검색할 수 없는 경우 이 함수는 인증서 컨텍스트에서 CERT_KEY_PROV_INFO_PROP_ID 속성을 다시 만들려고 시도하지 않습니다. |
|
CSP는 이 컨텍스트에 대한 UI(사용자 인터페이스)를 표시해서는 안 됩니다. CSP가 작동할 UI를 표시해야 하는 경우 호출이 실패하고 NTE_SILENT_CONTEXT 오류 코드가 마지막 오류로 설정됩니다. |
|
인증서의 CERT_KEY_PROV_INFO_PROP_ID 속성을 사용하여 캐싱을 수행할지 여부를 결정합니다. CERT_KEY_PROV_INFO_PROP_ID 속성에 대한 자세한 내용은 CertSetCertificateContextProperty를 참조하세요.
이 함수는 이전 호출 중에 CRYPT_KEY_PROV_INFO 구조체의 dwFlags 멤버가 CERT_SET_KEY_CONTEXT_PROP 포함된 경우에만 캐싱을 사용합니다. |
|
CSP 또는 KSP에 필요한 모든 UI는 pvParameters 매개 변수에 제공된 HWND의 자식이 됩니다. CSP 키의 경우 이 플래그를 사용하면 이 HWND를 사용하는 플래그 PP_CLIENT_HWND 있는 CryptSetProvParam 함수가 HCRYPTPROV용 NULL과 함께 호출됩니다. KSP 키의 경우 이 플래그를 사용하면 HWND를 사용하여 NCRYPT_WINDOW_HANDLE_PROPERTY 플래그가 있는 NCryptSetProperty 함수가 호출됩니다.
CRYPT_ACQUIRE_SILENT_FLAG 이 플래그를 사용하지 마세요. |
다음 플래그는 키를 가져오는 데 사용되는 기술을 결정합니다. 이러한 플래그가 없는 경우 이 함수는 CryptoAPI를 사용하여 키를 가져오려고 시도합니다.
Windows Server 2003 및 Windows XP: 이러한 플래그는 지원되지 않습니다.
[in, optional] pvParameters
CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG 설정된 경우 HWND의 주소입니다. CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG 설정되지 않은 경우 이 매개 변수는 NULL이어야 합니다.
Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 이 매개 변수의 이름은 pvReserved 이고 나중에 사용할 수 있을 때 예약되었으며 NULL이어야 합니다.
[out] phCryptProvOrNCryptKey
CryptoAPI 공급자 또는 CNG 키의 핸들을 수신하는 HCRYPTPROV_OR_NCRYPT_KEY_HANDLE 변수의 주소입니다. pdwKeySpec 변수가 CERT_NCRYPT_KEY_SPEC 플래그를 수신하는 경우 NCRYPT_KEY_HANDLE 형식의 CNG 키 핸들입니다. 그렇지 않으면 HCRYPTPROV 형식의 CryptoAPI 공급자 핸들입니다.
이 핸들을 해제하는 시기와 방법에 대한 자세한 내용은 pfCallerFreeProvOrNCryptKey 매개 변수에 대한 설명을 참조하세요.
[out] pdwKeySpec
키에 대한 추가 정보를 수신하는 DWORD 변수의 주소입니다. 다음 값 중 하나일 수 있습니다.
값 | 의미 |
---|---|
|
키 쌍은 키 교환 쌍입니다. |
|
키 쌍은 서명 쌍입니다. |
|
키는 CNG 키입니다.
Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다. |
[out] pfCallerFreeProvOrNCryptKey
호출자가 phCryptProvOrNCryptKey 변수에 반환된 핸들을 해제해야 하는지 여부를 나타내는 값을 수신하는 BOOL 변수의 주소입니다. 다음 중 어느 것이 true이면 FALSE 를 받습니다.
- 공개 키 획득 또는 비교가 실패합니다.
- dwFlags 매개 변수에는 CRYPT_ACQUIRE_CACHE_FLAG 플래그가 포함됩니다.
- dwFlags 매개 변수에는 CRYPT_ACQUIRE_USE_PROV_INFO_FLAG 플래그가 포함되고, 인증서 컨텍스트 속성은 CRYPT_KEY_PROV_INFO 구조체를 사용하여 CERT_KEY_PROV_INFO_PROP_ID 설정되며, CRYPT_KEY_PROV_INFO 구조체의 dwFlags 멤버는 CERT_SET_KEY_CONTEXT_PROP_ID 설정됩니다.
이 변수가 TRUE를 수신하면 호출자는 phCryptProvOrNCryptKey 변수에 반환된 핸들을 해제합니다. pdwKeySpec 변수가 CERT_NCRYPT_KEY_SPEC 값을 받으면 NCryptFreeObject 함수에 전달하여 핸들을 해제해야 합니다. 그렇지 않으면 핸들을 CryptReleaseContext 함수에 전달하여 해제됩니다.
함수가 성공하면 반환 값은 0이 아닌 값(TRUE)입니다.
함수가 실패하면 반환 값은 0(FALSE)입니다. 확장된 오류 정보는 GetLastError를 호출합니다. 가능한 오류 코드 중 하나는 다음과 같습니다.
반환 코드 | 설명 |
---|---|
|
인증서의 공개 키가 CSP에서 반환한 공개 키와 일치하지 않습니다. 이 오류 코드는 CRYPT_ACQUIRE_COMPARE_KEY_FLAG 설정되고 인증서의 공개 키가 암호화 공급자가 반환한 공개 키와 일치하지 않는 경우 반환됩니다. |
|
dwFlags 매개 변수에는 CRYPT_ACQUIRE_SILENT_FLAG 플래그가 포함되어 있으며 CSP는 사용자 인터페이스를 표시하지 않고 작업을 계속할 수 없습니다. |
CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG 설정되면 호출자는 HWND가 유효한지 확인해야 합니다. HWND가 더 이상 유효하지 않은 경우 CSP의 경우 호출자는 HWND의 경우 NULL과 HCRYPTPROV의 경우 NULL이 있는 플래그 PP_CLIENT_HWND 사용하여 CryptSetProvParam을 호출해야 합니다. KSP의 경우 호출자는 ncrypt 키의 NCRYPT_WINDOW_HANDLE_PROPERTY NULL로 설정해야 합니다. KSP에 대해 CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG 플래그를 설정하면 스토리지 공급자 및 키에 NCRYPT_WINDOW_HANDLE_PROPERTY 설정됩니다. 두 호출이 모두 실패하면 함수가 실패합니다. 하나만 실패하면 함수가 성공합니다. HWND를 NULL로 설정하면 HCRYPTPROV 또는 ncrypt 키에서 HWND가 효과적으로 제거됩니다.
이 함수를 사용하는 예제는 예제 C 프로그램: 서명된 메시지 및 암호화된 메시지 보내기 및 받기를 참조하세요.
지원되는 최소 클라이언트 | Windows XP [데스크톱 앱 | UWP 앱] |
지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
대상 플랫폼 | Windows |
헤더 | wincrypt.h |
라이브러리 | Crypt32.lib |
DLL | Crypt32.dll |