Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function acquires a HCRYPTPROVcryptographic service provider (CSP) handle including access to its related key container and the dwKeySpecparameter 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 CryptGetUserKeyfunction 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_CONTEXTstructure 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 HCRYPTPROVvalue is returned as the phCryptProvparameter. If an HCRYPTPROVvalue is already acquired and cached, that HCRYPTPROVvalue is returned. Otherwise, a new HCRYPTROVvalue is acquired and cached by using the certificate's CERT_KEY_CONTEXT_PROP_ID.

In any case, when this flag is set, the pfCallerFreeProvparameter returns FALSE and the calling application must not free the cached HCRYPTPROVvalue.

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 CertSetCertificateContextPropertyfunction.

Uses caching, but only if during a previous call the dwFlagsparameter of the CRYPT_KEY_PROV_INFOstructure 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 HCRYPTPROVvalue is returned, no comparison is made.
pvReserved

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

phCryptProv

[out] Pointer to the returned HCRYPTPROVvalue. Depending on the dwFlagsvalue, the HCRYPTPROVvalue must be freed by the calling application or explicitly freed on the last free action of the certificate context.

pdwKeySpec

[out] Pointer to a DWORDvalue 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_INFOstructure, and the dwFlagsparameter is set to CERT_SET_KEY_CONTEXT_PROP_ID.

If the fCallerFreeProvflag is returned FALSE, the calling application must not free the returned HCRYPTPROVvalue. The returned HCRYPTPROVvalue is freed on the last free action of the certificate context.

When the fCallerFreeProvflag is set to TRUE, the returned HCRYPTPROVvalue must be freed by calling the CryptReleaseContextfunction.

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 GetLastErrorfunction. 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