CertGetNameString

Windows CE 3.0

This function obtains the subject or issuer name from a certificate CERT_CONTEXT structure and converts it to a NULL-terminated character string.

DWORD WINAPI CertGetNameString(
PCCERT_CONTEXT pCertContext,
DWORD dwType,
DWORD dwFlags,
void *pvTypePara,
LPTSTR pszNameString,
DWORD cchNameString
);

Parameters

pCertContext
[in] Pointer to a CERT_CONTEXT structure's certificate context that includes a subject and issuer name to be converted.
dwType
The following table shows the defined values for the dwType parameter.
Value Description
CERT_NAME_EMAIL_TYPE If the certificate has a Subject Alternative Name extension or Issuer Alternative Name, uses the first rfc822Name choice. If no rfc822Name choice is found in the extension, it uses the Subject Name field for the Email OID. If either rfc822Name or the Email OID is found, it uses the string. Otherwise, it returns an empty string (returned character count is 1). The pvTypePara parameter is not used and is set to NULL.
CERT_NAME_RDN_TYPE Converts the Subject Name BLOB by calling the CertNameToStr function. pvTypePara points to a DWORD containing the dwStrType passed to the CertNameToStr function. If the Subject Name field is empty and the certificate has a Subject Alternative Name extension, uses the first directory Name choice from the CertNameToStr function.
CERT_NAME_ATTR_TYPE The pvTypePara parameter points to an OID specifying the name attribute to be returned. For example, if pvTypePara is szOID_COMMON_NAME, uses the Subject Name member. If the Subject Name member is empty and the certificate has a Subject Alternative Name extension, it uses the first directoryName choice.
CERT_NAME_SIMPLE_DISPLAY_TYPE Iterates through the following list of name attributes and uses the Subject Name or the Subject Alternative Name extension for the first occurrence of: szOID_COMMON_NAME, szOID_ORGANIZATIONAL_UNIT_NAME, szOID_ORGANIZATION_NAME, or szOID_RSA_emailAddr.

If one of these attributes is not found, it uses the Subject Alternative Name extension for a rfc822Name choice. If there still no match, it uses the first attribute.

The pvTypePara parameter is not used and is set to NULL.

CERT_NAME_FRIENDLY_DISPLAY_TYPE Checks the certificate for a CERT_FRIENDLY_NAME_PROP_ID property. If the certificate has this property, it is returned. If the certificate does not have the property, CERT_NAME_SIMPLE_DISPLAY_TYPE is returned.
dwFlags
[in] Indicates the type of processing needed. The following table shows the defined values for the dwFlags parameter.
Value Description
CERT_NAME_ISSUER_FLAG Acquires the issuer's name. If not set, it acquires the subject's name.
CERT_NAME_DISABLE_IE4_UTF8_FLAG Skips the default initial attempt to decode the value as UTF8 and decodes as 8-bit characters.
pvTypePara
[in] Pointer to either a DWORD containing the dwStrType parameter or an object identifier (OID) specifying the name attribute. The type pointed to is determined by the value of dwType.
pszNameString
[out] Pointer to an allocated buffer to receive the returned string. If the pszNameString parameter is not NULL and the cchNameString parameter is not zero, the pszNameString parameter is a NULL-terminated string.
cchNameString
[in] Size, in characters, allocated for the returned string. The size must include the terminating NULL character.

Return Values

Returns the number of characters converted, including the terminating zero character. If the pszNameString parameter is NULL or the cchNameString parameter is zero, returns the required size of the destination string (including the terminating NULL character). If the specified name type is not found, returns a NULL-terminated empty string with a returned character count of 1.

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 3.0 or later Wincrypt.h   Crypt32.lib
Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CertNameToStr, CERT_CONTEXT


 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.

Show: