CertGetNameString

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function obtains the subject or issuer name from a certificate CERT_CONTEXT structure 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_CONTEXT structure'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 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 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 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] 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 DWORD containing the dwStrType parameter or an OID specifying the name attribute. The type pointed to is determined by the value of the dwType parameter.

• 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 Value

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

See Also

Reference

CertNameToStr
CERT_CONTEXT