Edit

CertRetrieveLogoOrBiometricInfo function (wincrypt.h)

  • Article

The CertRetrieveLogoOrBiometricInfo function performs a URL retrieval of logo or biometric information specified in either the szOID_LOGOTYPE_EXT or szOID_BIOMETRIC_EXT certificate extension. The szOID_BIOMETRIC_EXT extension (IETF RFC 3739) supports the addition of a signature or a pictorial representation of the human holder of the certificate. The szOID_LOGOTYPE_EXT extension (IETF RFC 3709) supports the addition of organizational pictorial representations in certificates.

Syntax

BOOL CertRetrieveLogoOrBiometricInfo(
  [in]  PCCERT_CONTEXT pCertContext,
  [in]  LPCSTR         lpszLogoOrBiometricType,
  [in]  DWORD          dwRetrievalFlags,
  [in]  DWORD          dwTimeout,
  [in]  DWORD          dwFlags,
        void           *pvReserved,
  [out] BYTE           **ppbData,
  [out] DWORD          *pcbData,
  [out] LPWSTR         *ppwszMimeType
);

Parameters

[in] pCertContext

The address of a CERT_CONTEXT structure that contains the certificate.

[in] lpszLogoOrBiometricType

The address of a null-terminated ANSI string that contains an object identifier (OID) string that identifies the type of information to retrieve.

This parameter may also contain one of the following predefined values.

Value Meaning
CERT_RETRIEVE_ISSUER_LOGO
 Retrieve the certificate issuer logotype.
CERT_RETRIEVE_SUBJECT_LOGO
 Retrieve the certificate subject logotype.
CERT_RETRIEVE_COMMUNITY_LOGO
 Retrieve the certificate community logotype.
CERT_RETRIEVE_BIOMETRIC_PICTURE_TYPE
 Retrieve the picture associated with the certificate.
CERT_RETRIEVE_BIOMETRIC_SIGNATURE_TYPE
 Retrieve the signature associated with the certificate.

[in] dwRetrievalFlags

A set of flags that specify how the information should be retrieved. This parameter is passed as the dwRetrievalFlags in the CryptRetrieveObjectByUrl function.

[in] dwTimeout

The maximum amount of time, in milliseconds, to wait for the retrieval.

[in] dwFlags

This parameter is not used and must be zero.

pvReserved

This parameter is not used and must be NULL.

[out] ppbData

The address of a BYTE pointer that receives the logotype or biometric data. This memory must be freed when it is no longer needed by passing this pointer to the CryptMemFree function.

[out] pcbData

The address of a DWORD variable that receives the number of bytes in the ppbData buffer.

[out] ppwszMimeType

The address of a pointer to a null-terminated Unicode string that receives the Multipurpose Internet Mail Extensions (MIME) type of the data. This parameter can be NULL if this information is not needed. This memory must be freed when it is no longer needed by passing this pointer to the CryptMemFree function.

This address always receives NULL for biometric types. You must always ensure that this parameter contains a valid memory address before attempting to access the memory.

Return value

Returns nonzero if successful or zero otherwise.

For extended error information, call GetLastError. Possible error codes returned by the GetLastError function include, but are not limited to, the following.

Return code Description
CRYPT_E_HASH_VALUE
 The computed hash value does not match the hash value in the certificate.
CRYPT_E_NOT_FOUND
 The certificate does not contain the szOID_LOGOTYPE_EXT or szOID_BIOMETRIC_EXT extension, or the specified lpszLogoOrBiometricType was not found.
E_INVALIDARG
 One or more parameters are not valid.
ERROR_INVALID_DATA
 No data could be retrieved from the URL specified by the certificate extension.
ERROR_NOT_SUPPORTED
 The certificate does not support the required extension.
NTE_BAD_ALGID
 The hash algorithm OID is unknown.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header wincrypt.h
Library Crypt32.lib
DLL Crypt32.dll

See also

CryptMemFree