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 obtains the subject or issuer name from a certificate CERT_CONTEXTstructure and converts it to a NULL-terminated character string.

Syntax 

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

Parameters

pCertContext

[in] Pointer to a CERT_CONTEXTstructure's certificate context that includes a subject and issuer name to be converted.

dwType

[in] Specifies how the name can be found and how to format the output.

The following table shows the defined values for this 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 value for the e-mail object identifier (OID). If either rfc822Name or the e-mail OID is found, it uses the string. Otherwise, it returns an empty string (returned character count is 1). The pvTypeParaparameter is not used and is set to NULL.

CERT_NAME_RDN_TYPE

Converts the subject name BLOB by calling the CertNameToStrfunction. pvTypeParapoints to a DWORDcontaining the dwStrTypepassed to the CertNameToStrfunction. If the subject name field is empty and the certificate has a subject alternative name extension, uses the first directory name choice from the CertNameToStrfunction.

CERT_NAME_ATTR_TYPE

The pvTypeParaparameter points to an OID specifying the name attribute to be returned. For example, if pvTypeParais 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 directory name 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 is still no match, it uses the first attribute.

The pvTypeParaparameter 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] Specifies the type of processing needed. The following table shows the defined values for this 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 DWORDcontaining the dwStrTypeparameter or an OID specifying the name attribute. The type pointed to is determined by the value of the dwTypeparameter.

pszNameString

[out] Pointer to an allocated buffer to receive the returned string. If the pszNameStringparameter is not NULL and the cchNameStringparameter is not zero, the pszNameStringparameter is a NULL-terminated string.

cchNameString

[in] Size, in characters, allocated for the returned string. The size must include the terminating NULL character.

Return Value

Returns the number of characters converted, including the terminating zero character. If the pszNameStringparameter is NULL or the cchNameStringparameter 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

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