CryptAcquireCertificatePrivateKey

[This is preliminary documentation and subject to change.]

The CryptAcquireCertificatePrivateKey function acquires a HCRYPTPROV handle and dwKeySpec for the specified certificate context.

#include <wincrypt.h>
BOOL WINAPI CryptAcquireCertificatePrivateKey(
  PCCERT_CONTEXT pCert,        // in
  DWORD dwFlags,               // in
  void *pvReserved,            // in
  HCRYPTPROV *phCryptProv,     // out
  DWORD *pdwKeySpec,           // out, optional
  BOOL *pfCallerFreeProv       // out, optional
);
 

Parameters

pCert

Pointer to the specified certificate context. This is the certificate context for which a private key will be acquired.

dwFlags

The following flags are defined;

Flag name	value	Description
CRYPT_ACQUIRE_ CACHE_FLAG	0x1	A HCRYPTPROV is returned as a phCryptProv. If a HCRYPTPROV is already acquired and cached, that HCRYPTPROV is returned. Otherwise a new HCRYPTROV is acquired and cached via the certificate's CERT_KEY_CONTEXT_PROP_ID. In any case, when this flag is set, *pfCallerFreeProv is returned FALSE and the caller must not free the cached HCRYPTPROV
CRYPT_ACQUIRE_ USE_PROV_INFO_FLAG	0x2	Uses the certificate's property CERT_KEY_PROV_INFO_PROP_ID (see CertSetCertificateContextProperty) to determine if caching should be accomplished. Uses caching, only if during a previous call to CRYPT_KEY_PROV_INFO, the dwFlags was set to CERT_SET_KEY_CONTEXT_PROP.
CRYPT_ACQUIRE_ COMPARE_KEY_FLAG	0x4	The public key in the certificate is compared with the public key returned by the cryptographic service provider. If the keys do not match, the acquire fails and LastError is set to NTE_BAD_PUBLIC_KEY. If a cached HCRYPTPROV is returned, no comparison is made.

pvReserved

This parameter is reserved for future use and must be NULL.

phCryptProv

Pointer to the returned HCRYPTPROV. Depending on the dwFlags, HCRYPTPROV must be freed by the caller or explicitly freed on the last free action of the certificate context.

pdwKeySpec

Pointer to the specification of the private key.

The following dwKeySpec values are defined in Wincrypt.h for the default provider:

AT_KEYEXCHANGE	1
AT_SIGNATURE	2

pfCallerFreeProv

Pointer to a flag. The flag is returned set to FALSE if:

Acquire or public key comparison fails.

CRYPT_ACQUIRE_CACHE_FLAG is set.

CRYPT_ACQUIRE_USE_PROV_INFO_FLAG is set AND the certificate context property is set to CERT_KEY_PROV_INFO_PROP_ID with the CRYPT_KEY_PROV_INFO data structure, dwFlags paramater set to CERT_SET_KEY_CONTEXT_PROP_ID.

When the fCallerFreeProv flag is returned FALSE, the caller must not release the returned HCRYPTPROV. The returned HCRYPTPROV will be released on the last free action of the certificate context.

When the fCallerFreeProv flag is set TRUE, the returned HCRYPTPROV must be released by calling CryptReleaseContext.

Return Values

TRUE if the function succeeded, FALSE if the function failed.

Call GetLastError to see the reason for any failures.

Example

// EXAMPLE CODE FOR USING CryptAcquireCertificatePrivateKey().
// Assume that a pointer to the certificate (pCert) is already known.
// Set up the variables.
PCCERT_CONTEXT pCert;         // Pointer to the specified certificate
                              //   Initialized elsewhere
DWORD dwFlags = CRYPT_ACQUIRE_CACHE_FLAG;
                              // Flag is set. Search for a cached
                              //   HCRYPTPROV. If none is found,
                              //   acquire, and cache a HCRYPTPROV
void *pvReserved = NULL;      // This parameter is reserved for future
                              //   use and must be NULL.
HCRYPTPROV *phCryptProv;      // Pointer to the cached HCRYPTPROV
DWORD *pdwKeySpec;            // Pointer to the specification
                              //   of the private key
BOOL *pfCallerFreeProv;       // if *pfCallerFreeProv is returned
                              //   false do not release HCRYPTPROV.
BOOL fResult;                 // Return TRUE if the function succeeded
                              //   FALSE if the function failed

// Function call to CryptAcquireCertificatePrivateKey
// to get the handle of the matching HCRYPTPROV.
fResult= CryptAcquireCertificatePrivateKey(
           pCert,            // in - the HCRYPTPROV to be searched-
                             //   acquired elsewhere
           CRYPT_ACQUIRE_CACHE_FLAG, 
                             // in - dwFlags set to search and locate
                             //   an already acquired and cached
                             //   certificate or to acquire and
                             //   cache a certificate
           NULL,             // in - pvReserved is set to NULL
           phCryptProv,      // out - phCryptProv is the pointer
                             //   to the cached HCRYPTPROV
           pdwKeySpec,       // out, optional - pdwKeySpec is a
                             //   pointer to dwKeySpec for the
                             //   specified certificate
           pfCallerFreeProv);// out, optional

cout<< "CryptAcquireCertificatePrivateKey;"<< endl
    << "fResult = "<< fResult<< endl<< endl;
if (fResult) {               // returned value is TRUE
                             //   an acquire is successful
    cout<< "the HCRYPTPROV at "<< phCryptProv<< "is cached"<< endl
        << "the dwKeySpec is "<< &pdwKeySpec<< endl<< endl;
    if (*pfCallerFreeProv) { // TRUE- release HCRYPTPROV
        cout<< "release HCRYPTPROV"<< endl << endl;
        CryptReleaseContext( // call & release HCRYPTPROV.
        *phCryptProv,
        0);                  // set dwFlags to 0
     }
     else {                  // FALSE- do not release HCRYPTPROV
        cout<< "do not release HCRYPTPROV"<< endl << endl;
     }
}
else {                       // returned value is FALSE
     cout<< "acquire failed" << endl << endl;
}
}
 

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later. Available also in IE 3.02 and later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in wincrypt.h.
  Import Library: Use crypt32.lib.