CryptAcquireCertificatePrivateKey

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function acquires a HCRYPTPROV cryptographic service provider (CSP) handle including access to its related key container and the dwKeySpec parameter for a user's specified certificate context. This function is used to get access to a user's private key when the user's certificate is available and the handle of a CSP with the user's key container is not available. This function can 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 can be used.

Syntax

BOOL WINAPI CryptAcquireCertificatePrivateKey(
  PCCERT_CONTEXT pCert, 
  DWORD dwFlags,
  void* pvReserved,
  HCRYPTPROV* phCryptProv,
  DWORD* pdwKeySpec,
  BOOL* pfCallerFreeProv
);

Parameters

• pCert
  [in] Pointer to a CERT_CONTEXT structure containing the specified certificate context. This is the certificate context for which a private key will be acquired.

• dwFlags
  [in] Bitmask of flags. The following table shows values for this parameter.

  Value	Description
  CRYPT_ACQUIRE_CACHE_FLAG	An HCRYPTPROV value is returned as the phCryptProv parameter. If an HCRYPTPROV value is already acquired and cached, that HCRYPTPROV value is returned. Otherwise, a new HCRYPTROV value is acquired and cached by using the certificate's CERT_KEY_CONTEXT_PROP_ID. In any case, when this flag is set, the pfCallerFreeProv parameter returns FALSE and the calling application must not free the cached HCRYPTPROV value.
  CRYPT_ACQUIRE_USE_PROV_INFO_FLAG	Uses the certificate's property CERT_KEY_PROV_INFO_PROP_ID to determine if caching should be accomplished. For more information on CERT_KEY_PROV_INFO_PROP_ID, see the CertSetCertificateContextProperty function. Uses caching, but only if during a previous call the dwFlags parameter of the CRYPT_KEY_PROV_INFO structure was CERT_SET_KEY_CONTEXT_PROP.
  CRYPT_ACQUIRE_COMPARE_KEY_FLAG	The public key in the certificate is compared with the public key returned by the 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 HCRYPTPROV value is returned, no comparison is made.

• pvReserved
  [in] Reserved for future use and must be set to NULL.

• phCryptProv
  [out] Pointer to the returned HCRYPTPROV value. Depending on the dwFlags value, the HCRYPTPROV value must be freed by the calling application or explicitly freed on the last free action of the certificate context.

• pdwKeySpec
  [out] Pointer to a DWORD value identifying the private key to use from the acquired provider's key container. The value can be AT_KEYEXCHANGE or AT_SIGNATURE.

• pfCallerFreeProv
  [out] Pointer to a BOOL flag. The flag is returned set to FALSE if one of the following conditions is met:

  • Public key acquisition or comparison fails.
  • CRYPT_ACQUIRE_CACHE_FLAG is set.
  • CRYPT_ACQUIRE_USE_PROV_INFO_FLAG is set, the certificate context property is set to CERT_KEY_PROV_INFO_PROP_ID with the CRYPT_KEY_PROV_INFO structure, and the dwFlags parameter is set to CERT_SET_KEY_CONTEXT_PROP_ID.

  If the fCallerFreeProv flag is returned FALSE, the calling application must not free the returned HCRYPTPROV value. The returned HCRYPTPROV value is freed on the last free action of the certificate context.

  When the fCallerFreeProv flag is set to TRUE, the returned HCRYPTPROV value must be freed by calling the CryptReleaseContext function.

Return Value

If the function succeeds, the return value is nonzero, or TRUE.

If the function fails, the return value is zero, or FALSE.

For extended error information, call the GetLastError function. The following table shows one possible error code.

Value	Description
NTE_BAD_PUBLIC_KEY	The public key in the certificate does not match the public key returned by the CSP. This error code is returned if 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.

Requirements

Header	wincrypt.h
Library	crypt32.lib
Windows Embedded CE	Windows CE 3.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

HCRYPTPROV
CertSetCertificateContextProperty
CryptGetUserKey
CryptReleaseContext
CERT_CONTEXT
CRYPT_KEY_PROV_INFO