CryptAcquireCertificatePrivateKey function (wincrypt.h)
The CryptAcquireCertificatePrivateKey function obtains the private key for a certificate. This function is used to obtain access to a user's private key when the user's certificate is available, but the handle of the user's key container is not available. This function can only be used by the owner of a private key and not by any other user.
If a CSP handle and the key container containing a user's private key are available, the CryptGetUserKey function should be used instead.
Syntax
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
);
Parameters
[in] pCert
The address of a CERT_CONTEXT structure that contains the certificate context for which a private key will be obtained.
[in] dwFlags
A set of flags that modify the behavior of this function. This can be zero or a combination of one or more of the following values.
| Value | Meaning |
|---|---|
|
If a handle is already acquired and cached, that same handle is returned. Otherwise, a new handle is acquired and cached by using the certificate's CERT_KEY_CONTEXT_PROP_ID property.
When this flag is set, the pfCallerFreeProvOrNCryptKey parameter receives FALSE and the calling application must not release the handle. The handle is freed when the certificate context is freed; however, you must retain the certificate context referenced by the pCert parameter as long as the key is in use, otherwise operations that rely on the key will fail. |
|
The public key in the certificate is compared with the public key returned by the cryptographic service provider (CSP). If the keys do not match, the acquisition operation fails and the last error code is set to NTE_BAD_PUBLIC_KEY. If a cached handle is returned, no comparison is made. |
|
This function will not attempt to re-create the CERT_KEY_PROV_INFO_PROP_ID property in the certificate context if this property cannot be retrieved. |
|
The CSP should not display any user interface (UI) for this context. If the CSP must display UI to operate, the call fails and the NTE_SILENT_CONTEXT error code is set as the last error. |
|
Uses the certificate's CERT_KEY_PROV_INFO_PROP_ID property to determine whether caching should be accomplished. For more information about the CERT_KEY_PROV_INFO_PROP_ID property, see
CertSetCertificateContextProperty.
This function will only use caching if during a previous call, the dwFlags member of the CRYPT_KEY_PROV_INFO structure contained CERT_SET_KEY_CONTEXT_PROP. |
|
Any UI that is needed by the CSP or KSP will be a child of the HWND that is supplied in the pvParameters parameter. For a CSP key, using this flag will cause the CryptSetProvParam function with the flag PP_CLIENT_HWND using this HWND to be called with NULL for HCRYPTPROV. For a KSP key, using this flag will cause the NCryptSetProperty function with the NCRYPT_WINDOW_HANDLE_PROPERTY flag to be called using the HWND.
Do not use this flag with CRYPT_ACQUIRE_SILENT_FLAG. |
The following flags determine which technology is used to obtain the key. If none of these flags is present, this function will only attempt to obtain the key by using CryptoAPI.
Windows Server 2003 and Windows XP: These flags are not supported.
[in, optional] pvParameters
If the CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG is set, then this is the address of an HWND. If the CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG is not set, then this parameter must be NULL.
Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This parameter was named pvReserved and reserved for future use and must be NULL.
[out] phCryptProvOrNCryptKey
The address of an HCRYPTPROV_OR_NCRYPT_KEY_HANDLE variable that receives the handle of either the CryptoAPI provider or the CNG key. If the pdwKeySpec variable receives the CERT_NCRYPT_KEY_SPEC flag, this is a CNG key handle of type NCRYPT_KEY_HANDLE; otherwise, this is a CryptoAPI provider handle of type HCRYPTPROV.
For more information about when and how to release this handle, see the description of the pfCallerFreeProvOrNCryptKey parameter.
[out] pdwKeySpec
The address of a DWORD variable that receives additional information about the key. This can be one of the following values.
[out] pfCallerFreeProvOrNCryptKey
The address of a BOOL variable that receives a value that indicates whether the caller must free the handle returned in the phCryptProvOrNCryptKey variable. This receives FALSE if any of the following is true:
- Public key acquisition or comparison fails.
- The dwFlags parameter contains the CRYPT_ACQUIRE_CACHE_FLAG flag.
- The dwFlags parameter contains the CRYPT_ACQUIRE_USE_PROV_INFO_FLAG flag, the certificate context property is set to CERT_KEY_PROV_INFO_PROP_ID with the CRYPT_KEY_PROV_INFO structure, and the dwFlags member of the CRYPT_KEY_PROV_INFO structure is set to CERT_SET_KEY_CONTEXT_PROP_ID.
If this variable receives TRUE, the caller is responsible for releasing the handle returned in the phCryptProvOrNCryptKey variable. If the pdwKeySpec variable receives the CERT_NCRYPT_KEY_SPEC value, the handle must be released by passing it to the NCryptFreeObject function; otherwise, the handle is released by passing it to the CryptReleaseContext function.
Return value
If the function succeeds, the return value is nonzero (TRUE).
If the function fails, the return value is zero (FALSE). For extended error information, call GetLastError. One possible error code is the following.
| Return code | Description |
|---|---|
|
The public key in the certificate does not match the public key returned by the CSP. This error code is returned if the CRYPT_ACQUIRE_COMPARE_KEY_FLAG is set and the public key in the certificate does not match the public key returned by the cryptographic provider. |
|
The dwFlags parameter contained the CRYPT_ACQUIRE_SILENT_FLAG flag and the CSP could not continue an operation without displaying a user interface. |
Remarks
When CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG is set, the caller must ensure the HWND is valid. If the HWND is no longer valid, for CSP the caller should call CryptSetProvParam using flag PP_CLIENT_HWND with NULL for the HWND and NULL for the HCRYPTPROV. For KSP, the caller should set the NCRYPT_WINDOW_HANDLE_PROPERTY of the ncrypt key to be NULL. When CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG flag is set for KSP, the NCRYPT_WINDOW_HANDLE_PROPERTY is set on the storage provider and the key. If both calls fail, then the function fails. If only one fails, the function succeeds. Note that setting HWND to NULL effectively removes HWND from the HCRYPTPROV or ncrypt key.
Examples
For an example that uses this function, see Example C Program: Sending and Receiving a Signed and Encrypted Message.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | wincrypt.h |
| Library | Crypt32.lib |
| DLL | Crypt32.dll |