CertGetCertificateContextProperty

The CertGetCertificateContextProperty function gets a property of a specified certificate context.

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

Parameters

pCertContext

Pointer to the certificate context.

dwPropId

ID for the desired property. Currently defined IDs and the data type to be passed in pvData are listed in the following table.

Property ID	Value pvData type
CERT_KEY_PROV_HANDLE_PROP_ID	HCRYPTPROV
CERT_KEY_PROV_INFO_PROP_ID	CRYPT_KEY_PROV_INFO
CERT_SHA1_HASH_PROP_ID	ARRAY OF BYTES
CERT_MD5_HASH_PROP_ID	ARRAY OF BYTES
CERT_HASH_PROP_ID	ARRAY OF BYTES
CERT_KEY_CONTEXT_PROP_ID	CERT_KEY_CONTEXT
CERT_KEY_SPEC_PROP_ID	DWORD
CERT_ENHKEY_USAGE_PROP_ID	ARRAY OF BYTES
CERT_CTL_USAGE_PROP_ID	CERT_ENHKEY_USAGE_PROP_ID
CERT_FRIENDLY_NAME_PROP_ID	ARRAY OF BYTES
CERT_PVK_FILE_PROP_ID	ARRAY OF BYTES
CERT_SIGNATURE_HASH_PROP_ID	ARRAY OF BYTES
CERT_NEXT_UPDATE_LOCATION_PROP_ID	ARRAY OF BYTES
CERT_ACCESS_STATE_PROP_ID	DWORD

The following list presents the definitions for the dwPropId types:

CERT_KEY_PROV_HANDLE_PROP_ID: The hCryptProv returned in pvdata is obtained from the CERT_KEY_CONTEXT_PROP_ID
CERT_KEY_PROV_INFO_PROP_ID: Values are returned in the CRYPT_KEY_PROV_INFO data structure pointed to by pvData.
CERT_HASH_PROP_ID, CERT_SHA1_HASH_PROP_ID or CERT_MD5_HASH_PROP_ID: If the hash does not exist, it is computed using CryptHashCertificate. The existing or computed hash is pointed to by pvData. The length of the hash is 20 bytes for SHA1 and 16 bytes for MD5. If no hCryptProv was specified when the store was opened or this context was created using CertCreateCertificateContext, the default PROV_RSA_FULL provider calculates the hash.
pvData points to the array of bytes and not a HASH_BLOB as used by pvData in CertSetCertificateContextProperty.
CERT_KEY_CONTEXT_PROP_ID: pvData points to a CERT_KEY_CONTEXT structure.
CERT_KEY_SPEC_PROP_ID: A DWORD containing the specification of the private key (dwKeySpec) is returned in pvData. If the CERT_KEY_CONTEXT_PROP_ID exists, dwKeySpec is obtained from there. Otherwise, if the CERT_KEY_PROV_INFO_PROP_ID exists, it is the source of the dwKeySpec.
CERT_ENHKEY_USAGE_PROP_ID or CERT_CTL_USAGE_PROP_ID: An array of bytes containing an ASN.1 encoded CTL_USAGE data structure is returned in the location pointed to by pvdata. *pcbData returns with the length of the CTL_USAGE structure.
CERT_NEXT_UPDATE_LOCATION_PROP_ID: An array of bytes containing an ASN.1 encoded CERT_ALT_NAME_INFO data structure is returned in the location pointed to by pvData. *pcbData returns the length of the data structure. CERT_NEXT_UPDATE_LOCATION_PROP_ID if currently used only with CTLs.
CERT_FRIENDLY_NAME_PROP_ID: A NULL terminated unicode character string specifying the friendly name for a certificate, CRL, or CTL is returned in the location pointed to by pvdata. *pcbData returns the length of the string.
CERT_PVK_FILE_PROP_ID: A NULL terminated unicode, wide character string specifying the file name containing the private key associated with the certificate's public key is returned in the location pointed to by pvData. *pcbData returns the length of the string.
CERT_SIGNATURE_HASH_PROP_ID: If the hash does not exist, it is computed with CryptHashToBeSigned. The existing or computed hash of the signature is returned in the location pointed to by pvData. The length of the hash is 20 bytes for SHA and 16 for MD5.
CERT_ACCESS_STATE_PROP_ID: A DWORD that indicates whether writes to the certificate are persisted. It is not set if the certificate is in a memory store or in a registry based store that is opened as read only.
All other PROP_IDs: pvData points to the array of bytes and not a CRYPT_DATA_BLOB as used by pvData in CertSetCertificateContextProperty.

See the documentation on dwPropId in CertSetCertificateContextProperty for more details about each property ID.

pvData

Pointer to a buffer that receives the data as determined by dwPropId. Elements pointed to by fields in the pvData structure follow the structure. Therefore, the size contained in pcbData may exceed the size of the structure.

This parameter can be NULL to set the size of this information for memory allocation purposes. For more information, see Common In/Out Parameter Conventions.

pcbData

Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pvData parameter. When the function returns, the variable pointed to by the pcbData parameter contains the number of bytes to be stored in the buffer. This parameter can be NULL, only if pvData is NULL.

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:

ERROR_MORE_DATA: If the buffer specified by the pvData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code, and stores the required buffer size, in bytes, into the variable pointed to by pcbData.
CRYPT_E_NOT_FOUND: The certificate does not have the specified property.

Errors from the called function CryptHashCertificate may be propagated to this function.

Example

See CertEnumCertificateContextProperties.

QuickInfo

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

CertGetCertificateContextProperty

Parameters

Return Values

Example

QuickInfo

See Also