CertSetCTLContextProperty function (wincrypt.h)
The CertSetCTLContextProperty function sets an extended property for the specified certificate trust list (CTL) context.
Syntax
BOOL CertSetCTLContextProperty(
[in] PCCTL_CONTEXT pCtlContext,
[in] DWORD dwPropId,
[in] DWORD dwFlags,
[in] const void *pvData
);
Parameters
[in] pCtlContext
A pointer to the CTL_CONTEXT structure.
[in] dwPropId
Identifies the property to be set. The value of dwPropId determines the type and content of the pvData parameter. Currently defined identifiers and their related pvData types are as follows.
Value | Meaning |
---|---|
|
Data type of pvData: 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. |
|
Data type of pvData: pointer to a CRYPT_DATA_BLOB
Property set after a certificate has been enrolled using Auto Enroll. The CRYPT_DATA_BLOB structure pointed to by pvData 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. |
|
Data type of pvData: pointer to a CRYPT_DATA_BLOB
pvData points to a CRYPT_DATA_BLOB structure containing an Abstract Syntax Notation One (ASN.1) encoded CTL_USAGE structure. This structure was encoded using CryptEncodeObject with X509_ENHANCED_KEY_USAGE value set. |
|
Data type of pvData: pointer to a CRYPT_DATA_BLOB
Property set and displayed by the certificate UI. This property allows the user to describe the certificate's use. |
|
Data type of pvData: pointer to a CRYPT_DATA_BLOB
The CRYPT_DATA_BLOB structure containing an ASN.1 encoded CERT_ENHKEY_USAGE structure. This structure was encoded using CryptEncodeObject with X509_ENHANCED_KEY_USAGE value set. |
|
Data type of pvData: pointer to a CRYPT_DATA_BLOB
The CRYPT_DATA_BLOB structure specifies the display name of the certificate. |
|
Data type of pvData: pointer to a CRYPT_HASH_BLOB
This property is implicitly set by a call to CertGetCertificateContextProperty. |
|
Data type of pvData: pointer to a CERT_KEY_CONTEXT
The CERT_KEY_CONTEXT structure contains both the HCRYPTPROV value and the key specification for the private key. For more information about the hCryptProv member and dwFlags settings, see CERT_KEY_PROV_HANDLE_PROP_ID, following. 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 |
|
Data type of pvData: pointer to a CRYPT_DATA_BLOB
This property is typically implicitly set by a call to CertGetCertificateContextProperty. |
|
Data type of pvData: pointer to a HCRYPTPROV
An HCRYPTPROV handle for the certificate's private key is passed. The hCryptProv member of the CERT_KEY_CONTEXT structure is updated if it exists. If it does not exist, it is created with dwKeySpec initialized by CERT_KEY_PROV_INFO_PROP_ID. If CERT_STORE_NO_CRYPT_RELEASE_FLAG is not set, the hCryptProv value is implicitly released either when the property is set to NULL or on the final freeing of the CERT_CONTEXT structure. |
|
Data type of pvData: pointer to a CRYPT_KEY_PROV_INFO
The CRYPT_KEY_PROV_INFO structure specifies the certificate's private key. |
|
Data type of pvData: pointer to a DWORD
The DWORD value specifies the private key. The dwKeySpec member of the CERT_KEY_CONTEXT structure is updated if it exists. If it does not, it is created with hCryptProv set to zero. |
|
Data type of pvData: pointer to a CRYPT_HASH_BLOB
This property is implicitly set by a call to CertGetCertificateContextProperty. |
|
Data type of pvData: pointer to a CRYPT_DATA_BLOB
The CRYPT_DATA_BLOB structure contains an ASN.1 encoded CERT_ALT_NAME_INFO structure encoded using CryptEncodeObject with the X509_ALTERNATE_NAME value set. CERT_NEXT_UPDATE_LOCATION_PROP_ID is currently used only with CTLs. |
|
Data type of pvData: pointer to a 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. |
|
Data type of pvData: pointer to a CRYPT_HASH_BLOB
This property is implicitly set by a call to CertGetCertificateContextProperty. |
|
Data type of pvData: pointer to a CRYPT_HASH_BLOB
If a signature hash does not exist, it is computed with CryptHashToBeSigned. pvData points to an existing or computed hash. Usually, the length of the hash is 20 bytes for SHA and 16 for MD5. |
Typically, only the CERT_NEXT_UPDATE_LOCATION_PROP_ID property is set.
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, pvData points to an encoded CRYPT_DATA_BLOB structure.
[in] dwFlags
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.
If CERT_SET_PROPERTY_INHIBIT_PERSIST_FLAG is set, any property set is not persisted.
[in] pvData
A pointer to a data type that is determined by the value passed in dwPropId.
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 GetLastError. One possible error code is the following.
Return code | Description |
---|---|
|
Invalid property identifier. For details, see CertSetCertificateContextProperty. |
Remarks
If a property already exists, its old value is replaced.
Examples
See Example C Program: Getting and Setting Certificate Properties.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps | UWP apps] |
Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
Target Platform | Windows |
Header | wincrypt.h |
Library | Crypt32.lib |
DLL | Crypt32.dll |