CryptAcquireCertificatePrivateKey function
Applies to: desktop apps only
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 WINAPI CryptAcquireCertificatePrivateKey( __in PCCERT_CONTEXT pCert, __in DWORD dwFlags, __in void *pvReserved, __out HCRYPTPROV_OR_NCRYPT_KEY_HANDLE *phCryptProvOrNCryptKey, __out DWORD *pdwKeySpec, __out BOOL *pfCallerFreeProvOrNCryptKey );
Parameters
- pCert [in]
-
The address of a CERT_CONTEXT structure that contains the certificate context for which a private key will be obtained.
- dwFlags [in]
-
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 - CRYPT_ACQUIRE_CACHE_FLAG
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.
- CRYPT_ACQUIRE_COMPARE_KEY_FLAG
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.
- CRYPT_ACQUIRE_NO_HEALING
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.
- CRYPT_ACQUIRE_SILENT_FLAG
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.
- CRYPT_ACQUIRE_USE_PROV_INFO_FLAG
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.
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, Windows XP, and Windows 2000: These flags are not supported. - pvReserved [in]
-
Reserved for future use and must be NULL.
- phCryptProvOrNCryptKey [out]
-
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.
- pdwKeySpec [out]
-
The address of a DWORD variable that receives additional information about the key. This can be one of the following values.
- pfCallerFreeProvOrNCryptKey [out]
-
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 FALSE, the calling application must not release the handle returned in the phCryptProvOrNCryptKey variable. The handle will be released on the last free action of the certificate context.
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 flag, 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. |
Examples
For an example that uses this function, see Example C Program: Sending and Receiving a Signed and Encrypted Message.
Requirements
|
Minimum supported client | Windows 2000 Professional |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
- Key Generation and Exchange Functions
- CRYPT_KEY_PROV_INFO
- CryptReleaseContext
- CertSetCertificateContextProperty
Send comments about this topic to Microsoft
Build date: 3/6/2012
[DllImport("crypt32.dll", CharSet=CharSet.Auto, SetLastError=true)]
internal static extern bool CryptAcquireCertificatePrivateKey([In] IntPtr pCert, [In] uint dwFlags, [In] IntPtr pvReserved, [In, Out] ref IntPtr phCryptProv, [In, Out] ref uint pdwKeySpec, [In, Out] ref bool pfCallerFreeProv);
- 5/6/2009
- dmex
<DllImport("crypt32.dll", CharSet:=CharSet.Auto, SetLastError:=True)> _
Public Shared Function CryptAcquireCertificatePrivateKey(<[In]> ByVal pCert As IntPtr, <[In]> ByVal dwFlags As UInt32, <[In]> ByVal pvReserved As IntPtr, <[In], Out> ByRef phCryptProv As IntPtr, <[In], Out> ByRef pdwKeySpec As UInt32, <[In], Out> ByRef pfCallerFreeProv As Boolean) As Boolean
End Function
- 5/6/2009
- dmex
