Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function retrieves the information contained in an extended property of a certificate context.

Syntax 

BOOL WINAPI CertGetCertificateContextProperty(
  PCCERT_CONTEXT 
pCertContext,
  DWORD 
dwPropId,
  void* 
pvData,
  DWORD* 
pcbData
);

Parameters

pCertContext

[in] Pointer to the CERT_CONTEXTstructure of the certificate containing the property to be retrieved.

dwPropId

[in] Specifies the property to be retrieved. The following table shows the currently defined identifiers and the data type to be returned in the pvDataparameter.

Property identified pvDatatype Description

CERT_ACCESS_STATE_PROP_ID

DWORD

Returns a DWORDvalue indicating whether write operations to the certificate are persisted. The DWORDvalue is not set if the certificate is in a memory store or in a registry-based store that is opened as read-only.

CERT_ARCHIVED_PROP_ID

NULL

Indicates the certificate is skipped during enumerations. A certificate with this property set is found with explicit search operations, such as those used to find a certificate with a specific hash or a serial number. No data in pvDatais associated with this property.

CERT_AUTO_ENROLL_PROP_ID

Array of BYTEs

Returns a NULL-terminated Unicode string naming the certificate type for which the certificate has been auto enrolled.

CERT_DESCRIPTION_PROP_ID

Array of BYTEs

Returns the property displayed by the certificate UI. This property allows the user to describe the certificate's use.

CERT_ENHKEY_USAGE_PROP_ID

Array of BYTEs

Returns an array of bytes containing an ASN.1 encoded CERT_ENHKEY_USAGEstructure. This structure contains an array of enhanced key usage OIDs, each specifying a valid use of the certificate.

CERT_FRIENDLY_NAME_PROP_ID

Array of BYTEs

Returns a NULL-terminated Unicode character string specifying the friendly name for the certificate.

CERT_HASH_PROP_ID

Array of BYTEs

Returns the SHA1 hash. If the hash does not exist, it is computed using the CryptHashCertificatefunction.

CERT_KEY_CONTEXT_PROP_ID

CERT_KEY_CONTEXT

Returns a CERT_KEY_CONTEXTstructure.

CERT_KEY_IDENTIFIER_PROP_ID

Array of BYTEs

If nonexistent, searches for the szOID_SUBJECT_KEY_IDENTIFIER extension. If that fails, a SHA1 hash is done on the certificate's SubjectPublicKeyInfoto produce the identifier values.

CERT_KEY_PROV_HANDLE_PROP_ID

HCRYPTPROV

Returns the provider handle obtained from CERT_KEY_CONTEXT_PROP_ID.

CERT_KEY_PROV_INFO_PROP_ID

CRYPT_KEY_PROV_INFO

Returns a pointer to CRYPT_KEY_PROV_INFO.

CERT_KEY_SPEC_PROP_ID

DWORD

Returns a DWORDvalue specifying the private key obtained from CERT_KEY_CONTEXT_PROP_ID if it exists. Otherwise, if CERT_KEY_PROV_INFO_PROP_ID exists, it is the source of the dwKeySpec.

CERT_MD5_HASH_PROP_ID

Array of BYTEs

Returns the MD5 hash. If the hash does not exist, it is computed using the CryptHashCertificatefunction.

CERT_PUBKEY_ALG_PROP_ID

Array of BYTES

Returns the ASN.1 encoded public key algorithm parameters. This property will only be set for public keys supporting algorithm parameter inheritance and when the parameters have been omitted for the encoded and signed certificate.

CERT_PVK_FILE_PROP_ID

Array of BYTEs

Returns a NULL-terminated Unicode, wide character string specifying the file name containing the private key associated with the certificate's public key.

CERT_SHA1_HASH_PROP_ID

Array of BYTEs

Returns the SHA1 hash. If the hash does not exist, it is computed using the CryptHashCertificatefunction.

CERT_SIGNATURE_HASH_PROP_ID

Array of BYTEs

Returns the signature hash. If the hash does not exist, it is computed with the CryptHashToBeSignedfunction. The length of the hash is 20 bytes for SHA and 16 for MD5.

For all other property identifiers, the pvDataparameter points to an array of bytes and not a CRYPT_DATA_BLOBstructure as pointed to by the pvDataparameter in the CertSetCertificateContextPropertyfunction.

For more details about each property identifier, see the documentation for the dwPropIdparameter in the CertSetCertificateContextPropertyfunction.

pvData

[out] Pointer to a buffer to receive the data as determined by the dwPropIdparameter. Structures pointed to by members of a structure returned are also returned following the base structure. Therefore, the size contained in the pcbDataparameter often exceeds the size of the base structure.

This parameter can be NULL to set the size of the information for memory allocation purposes.

pcbData

[in, out] On input, pointer to a DWORDvalue specifying the size, in bytes, of the buffer pointed to by the pvDataparameter. On output, the DWORDvalue contains the number of bytes to be stored in the buffer.

When processing the data returned in the buffer, applications must use the actual size of the data returned. The actual size can be slightly smaller than the size of the buffer specified on input. On input, buffer sizes are usually specified large enough to ensure that the largest possible output data fits in the buffer. On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

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 GetLastErrorfunction. The following table shows possible error codes.

Value Description

CRYPT_E_NOT_FOUND

The certificate does not have the specified property.

ERROR_MORE_DATA

If the buffer specified by the pvDataparameter 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, in the variable pointed to by the pcbDataparameter.

Errors from the called CryptHashCertificatefunction can be propagated to this function.

Requirements

Header wincrypt.h
Library crypt32.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also