CertSetCertificateContextProperty

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function sets an extended property for a specified certificate context.

Syntax

BOOL WINAPI CertSetCertificateContextProperty(
  PCCERT_CONTEXT pCertContext,
  DWORD dwPropId,
  DWORD dwFlags,
  const void* pvData
);

Parameters

• pCertContext
  [in] Pointer to a CERT_CONTEXT structure.

• dwPropId
  [in] Specifies the property to be set. The value of the dwPropId parameter determines the type and content of the pvData parameter. The following table shows currently defined identifiers and their related pvData types.

  Property identifier	pvData type	Description
  CERT_ARCHIVED_PROP_ID	NULL	Indicates the certificate is skipped during enumerations. A certificate with this property set is still found with explicit search operations, such as finding a certificate with a specific hash or a specific serial number.
  CERT_AUTO_ENROLL_PROP_ID	CRYPT_DATA_BLOB	Property set after a certificate has been enrolled using Auto Enroll. The CRYPT_DATA_BLOB structure pointed to by the pvData parameter includes a NULL-terminated, Unicode name of the certificate type for which the certificates has been auto enrolled. Any subsequent calls to Auto Enroll for the certificate checks for this property to determine whether the certificate has been enrolled.
  CERT_CTL_USAGE_PROP_ID	CRYPT_DATA_BLOB	The pvData parameter points to a CRYPT_DATA_BLOB structure containing an ASN.1 encoded CTL_USAGE structure. This structure was encoded using the CryptEncodeObject function with the X509_ENHANCED_KEY_USAGE value set.
  CERT_DESCRIPTION_PROP_ID	CRYPT_DATA_BLOB	Property set and displayed by the certificate UI. This property allows the user to describe the certificate's use.
  CERT_ENHKEY_USAGE_PROP_ID	CRYPT_DATA_BLOB	Property that indicates the pvData parameter points to a CRYPT_DATA_BLOB structure containing an ASN.1 encoded CERT_ENHKEY_USAGE structure. This structure was encoded using the CryptEncodeObject function with the X509_ENHANCED_KEY_USAGE value set.
  CERT_FRIENDLY_NAME_PROP_ID	CRYPT_DATA_BLOB	The pvData parameter points to a CRYPT_DATA_BLOB structure specifying the friendly name of the certificate.
  CERT_HASH_PROP_ID	CRYPT_HASH_BLOB	This property is implicitly set by a call to the CertGetCertificateContextProperty function.
  CERT_KEY_CONTEXT_PROP_ID	CERT_KEY_CONTEXT	The CERT_KEY_CONTEXT structure specifying the certificate's private key. It contains both the HCRYPTPROV and key specification for the private key. For more information about the HCRYPTPROV member and dwFlags settings, see CERT_KEY_PROV_HANDLE_PROP_ID, which follows. Note that more CERT_KEY_CONTEXT structure members can be added for this property. If so, the cbSize member value will be adjusted accordingly. The cbSize member must be set to the size of the CERT_KEY_CONTEXT structure
  CERT_KEY_IDENTIFIER_PROP_ID	CRYPT_DATA_BLOB	This property is typically implicitly set by a call to CertGetCertificateContextProperty.
  CERT_KEY_PROV_HANDLE_PROP_ID	HCRYPTPROV	An HCRYPTPROV handle for the certificate's private key is passed. The hCryptProv member of the CERT_KEY_CONTEXT_PROP_ID structure is updated if it exists. If it does not exist, it is created with the dwKeySpec parameter initialized by CERT_KEY_PROV_INFO_PROP_ID. If CERT_STORE_NO_CRYPT_RELEASE_FLAG is not set, the HCRYPTPROV value is implicitly freed either when the property is set to NULL or on the final freeing of the CERT_CONTEXT structure.
  CERT_KEY_PROV_INFO_PROP_ID	CRYPT_KEY_PROV_INFO	The CRYPT_KEY_PROV_INFO structure specifies the certificate's private key.
  CERT_KEY_SPEC_PROP_ID	DWORD	DWORD value specifying the private key. The dwKeySpec member of the CERT_KEY_CONTEXT_PROP_ID structure is updated if it exists. If it does not, it is created with hCryptProv set to zero.
  CERT_MD5_HASH_PROP_ID	CRYPT_HASH_BLOB	This property is implicitly set by a call to the CertGetCertificateContextProperty function.
  CERT_PUBKEY_ALG_PARA_PROP_ID	CRYPT_DATA_BLOB	Used with public keys supporting algorithm parameter inheritance. The data BLOB contains the ASN.1 encoded public key algorithm parameters. For DSS, these are parameters encoded using the CryptEncodeObject function. This is used only if CMS_PKCS7 is defined.
  CERT_PVK_FILE_PROP_ID	CRYPT_DATA_BLOB	The CRYPT_DATA_BLOB structure specifies the name of a file containing the private key associated with the certificate's public key. Inside the CRYPT_DATA_BLOB structure, the pbData member is a pointer to a NULL-terminated Unicode, wide-character string and the cbData member indicates the length of the string
  CERT_SHA1_HASH_PROP_ID	CRYPT_HASH_BLOB	This property is implicitly set by a call to the CertGetCertificateContextProperty function.
  CERT_SIGNATURE_HASH_PROP_ID	CRYPT_HASH_BLOB	If a signature hash does not exist, it is computed with the CryptHashToBeSigned function. The pvData parameter points to an existing or computed hash. Usually, the length of the hash is 20 bytes for SHA and 16 for MD5.
  CERT_CROSS_CERT_DIST_POINTS_PROP_ID	CRYPT_DATA_BLOB	Location of the cross certificates.
  CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID	CRYPT_DATA_BLOB	MD5 hash of the public key associated with the private key used to sign this certificate.
  CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID	CRYPT_DATA_BLOB	MD5 hash of this certificate's public key.
  CERT_ENROLLMENT_PROP_ID	CRYPT_DATA_BLOB	Enrollment information of the pending request containing RequestID, CADNSName, CAName, and FriendlyName. The data format is defined as: the first 4 bytes, pending request ID; next 4 bytes, CADNSName size in characters including null-terminator followed by CADNSName string with null-terminator; next 4 bytes, CAName size in characters including null-terminator followed by CAName string with null-terminator; next 4 bytes, FriendlyName size in characters including null-terminator followed by FriendlyName string with null-terminator.

  Additional dwPropId types can be defined by the user using DWORD values from CERT_FIRST_USER_PROP_ID to CERT_LAST_USER_PROP_ID. For all user-defined dwPropId types, the pvData parameter points to an encoded CRYPT_DATA_BLOB structure.

• dwFlags
  [in] Bitmask of flags. A value of CERT_STORE_NO_CRYPT_RELEASE_FLAG can be set for the CERT_KEY_PROV_HANDLE_PROP_ID or CERT_KEY_CONTEXT_PROP_ID dwPropId properties.

  If the CERT_SET_PROPERTY_IGNORE_PERSIST_ERROR_FLAG value is set, any provider-write errors are ignored and the cached context's properties are always set.

• pvData
  [in] Pointer to a data type determined by the value of the dwPropId parameter.

  For any dwPropId, setting pvData to NULL deletes the property.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

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

The GetLastError function can return E_INVALIDARG, which indicates an invalid property. The identifier specified was greater than 0x0000FFFF, or for the CERT_KEY_CONTEXT_PROP_ID property, an invalid cbSize member was specified in the CERT_KEY_CONTEXT structure.

Remarks

If a property already exists, its old value is replaced.

The desktop operating system supports the CERT_NEXT_UPDATE_LOCATION_PROP_ID property identifier; Windows Embedded CE does not.

Requirements

See Also

Reference

HCRYPTPROV
CertGetCertificateContextProperty
CryptHashToBeSigned
CERT_CONTEXT
CERT_KEY_CONTEXT
BLOB (Cryptography)
BLOB (Cryptography)
CRYPT_KEY_PROV_INFO
CTL_USAGE