CertSetCertificateContextProperty

The CertSetCertificateContextProperty function sets a property for the specified certificate context.

#include <wincrypt.h>
BOOL WINAPI CertSetCertificateContextProperty(
  PCCERT_CONTEXT pCertContext,     // in
  DWORD dwPropId,                  // in
  DWORD dwFlags,                   // in
  void *pvData                     // in
);

Parameters

pCertContext

Pointer to a certificate context.

dwPropId

DWORD identifying the property to be set. The value of dwPropId determines the type and content of the pvData parameter Currently defined IDs and their related pvData types are:

Property ID	pvData type
CERT_KEY_PROV_HANDLE_PROP_ID	HCRYPTPROV
CERT_KEY_PROV_INFO_PROP_ID	CRYPT_KEY_PROV_INFO
CERT_HASH_PROP_ID	CRYPT_HASH_BLOB
CERT_SHA1_HASH_PROP_ID	CRYPT_HASH_BLOB
CERT_MD5_HASH_PROP_ID	CRYPT_HASH_BLOB
CERT_KEY_CONTEXT_PROP_ID	CERT_KEY_CONTEXT
CERT_KEY_SPEC_PROP_ID	DWORD
CERT_ENHKEY_USAGE_PROP_ID	CRYPT_DATA_BLOB
CERT_CTL_USAGE_PROP_ID	CRYPT_DATA_BLOB
CERT_FRIENDLY_NAME_PROP_ID	CRYPT_DATA_BLOB
CERT_PVK_FILE_PROP_ID	CRYPT_DATA_BLOB
CERT_NEXT_UPDATE_LOCATION_PROP_ID	CRYPT_DATA_BLOB
CERT_SIGNATURE_HASH_PROP_ID	CRYPT_HASH_BLOB

The following list presents the definitions for the dwPropId types:

CERT_KEY_PROV_HANDLE_PROP_ID: A HCRYPTPROV handle for the certificate's private key is passed in pvData The hCryptProv field of the CERT_KEY_CONTEXT_PROP_ID is updated if it exists. If it does not exist, it is created with dwKeySpec initialized from CERT_KEY_PROV_INFO_PROP_ID. If the CERT_STORE_NO_CRYPT_RELEASE_FLAG is not set, the HCRYPTPROV is implicitly released either when the property is set to NULL or on the final freeing of the CERT_CONTEXT.
CERT_KEY_PROV_INFO_PROP_ID: pvData points to a CRYPT_KEY_PROV_INFO structure specifying the certificate's private key.
CERT_HASH_PROP_ID, CERT_SHA1_HASH_PROP_ID and CERT_MD5_HASH_PROP_ID: Typically, this property is implicitly set by a call to CertGetCertificateContextProperty.
CERT_KEY_CONTEXT_PROP_ID: pvData points to a CERT_KEY_CONTEXT structure specifying the certificate's private key. The CERT_KEY_CONTEXT contains both the HCRYPTPROV and dwKeySpec for the private key. See the CERT_KEY_PROV_HANDLE_PROP_ID for more information about the HCRYPTPROV field and dwFlags settings. Note that more fields may be added for this property. The cbSize field value will be adjusted accordingly. cbSize must be set to the size of CERT_KEY_CONTEXT.
CERT_KEY_SPEC_PROP_ID: pvData points to a DWORD that specifies the private key. The dwKeySpec field of the CERT_KEY_CONTEXT_PROP_ID is updated if it exists. If it does not, it is created with hCryptProv set to zero.
CERT_ENHKEY_USAGE_PROP_ID and CERT_CTL_USAGE_PROP_ID: pvData points to a CRYPT_DATA_BLOB containing an ASN.1 encoded CTL_USAGE data structure encoded using CryptEncodeObject(X509_ENHANCED_KEY_USAGE).
CERT_NEXT_UPDATE_LOCATION_PROP_ID: pvData points to a CRYPT_DATA_BLOB containing an ASN.1 encoded CERT_ALT_NAME_INFO data structure encoded using CryptEncodeObject(X509_ALTERNATE_NAME). CERT_NEXT_UPDATE_LOCATION_PROP_ID is currently used only with CTLs.
CERT_FRIENDLY_NAME_PROP_ID: pvData points to a CRYPT_DATA_BLOB, specifying the friendly name for a certificate, CRL or CTL. Inside the CRYPT_DATA_BLOB, the pbData member is a pointer to a NULL terminated unicode, wide character string, and cbData indicates the length of the string.
CERT_PVK_FILE_PROP_ID: pvData points to a CRYPT_DATA_BLOB that specifies the name of a file that contains the private key associated with the certificate's public key. Inside the CRYPT_DATA_BLOB, the pbData member is a pointer to a NULL terminated unicode, wide character string, and cbData indicates the length of the string.
CERT_SIGNATURE_HASH_PROP_ID: If a signature hash does not exist, it is computed with CryptHashToBeSigned. pvData to points to an existing or computed hash. Normally the length of the hash is 20 bytes for SHA and 16 for MD5.

Additional dwPropId types may be defined by the user using DWORD values from CERT_FIRST_USER_PROP_ID to CERT_LAST_USER_PROP_ID. For all user defined dwPropIds, pvData should point to an encoded CRYPT_DATA_BLOB.

dwFlags

The CERT_STORE_NO_CRYPT_RELEASE_FLAG can be set for the CERT_KEY_PROV_HANDLE_PROP_ID or CERT_KEY_CONTEXT_PROP_ID properties.

pvData

Pointer to a data type that is determined by the value of dwPropId. For any dwPropId, setting pvData to NULL deletes that property.

Return Values

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

GetLastError may be called to indicate the reason for any failure. This function uses the following error code:

E_INVALIDARG: Invalid property. The ID specified was greater than 0x0000FFFF, or, for the CERT_KEY_CONTEXT_PROP_ID property, an invalid cbSize in the CERT_KEY_CONTEXT structure was specified.

Remarks

If the property already exists, then the old value is replaced.

Example

// 
// Set the CERT_KEY_PROV_INFO_PROP_ID property 
// for a certificate context.
HCERTSTORE          hStoreHandle;
PCCERT_CONTEXT      pCertContext;      
CRYPT_KEY_PROV_INFO *pCryptKeyProvInfo;
LPWSTR              ContainerName = L"Jack Fink";
DWORD               dwPropId = CERT_KEY_PROV_INFO_PROP_ID; 
DWORD               dwFlags =  CERT_STORE_NO_CRYPT_RELEASE_FLAG;

// Open a store as the source of the certificate
// that is to have a property added to it.
if(hStoreHandle = CertOpenSystemStore(0,"MY"))
printf("The MY store is open. Continue. \n");
else
handle_error("The first system store did not open.");
//
// Get a certificate from the MY store.
if(pCertContext=CertEnumCertificatesInStore(
hStoreHandle,NULL))
printf("A certificate is available. Continue.\n");
else
handle_error("No certificate was retrieved.\n\
Perhaps the store is empty.");
//
// Initalize the CRYPT_KEY_PROV_INFO data structure.
// Note: pwszContainerName and pwszProvName can be set to NULL 
// to use the default container and provider.
pCryptKeyProvInfo->pwszContainerName = ContainerName ;
pCryptKeyProvInfo->pwszProvName = MS_ENHANCED_PROV_W;
pCryptKeyProvInfo->dwProvType = PROV_RSA_FULL;
pCryptKeyProvInfo->dwFlags = 0;
pCryptKeyProvInfo->cProvParam = 0;
pCryptKeyProvInfo->rgProvParam = NULL;
pCryptKeyProvInfo->dwKeySpec = AT_SIGNATURE;
//
// Set the property.
if(CertSetCertificateContextProperty(
     pCertContext,       // A pointer to the certificate
                         // where the propertiy will be set.
     dwPropId,           // An identifier of the property to be set. 
                         // In this case, CERT_KEY_PROV_INFO_PROP_ID
                         // is to be set to provide a pointer with the
                         // certificate to its associated private key 
                         // container.
     dwFlags,            // The flag used in this case is   
                         // CERT_STORE_NO_CRYPT_RELEASE_FLAG
                         // indicating that the cryptographic 
                         // context aquired should not
                         // be released when the function finishes.
     pCryptKeyProvInfo   // A pointer to a data structure that holds
                         // infomation on the private key container to
                         // be associated with this certificate.
     ))
printf("The property has been set. Continue.\n");
else
handle_error("The main function failed\n \
//
// The function worked as planned.
// Continue as desired.
printf("The program finished without errors.\n");

QuickInfo