CertGetNameString

The CertGetNameString function gets the subject or issuer name from the certificate and converts it to a null terminated character string.

#include <wincrypt.h>
DWORD WINAPI CertGetNameString(
  PCCERT_CONTEXT pCertContext,    // in
  DWORD dwType,                   // in
  DWORD dwFlags,                  // in
  void *pvTypePara,               // in
  LPTSTR pszNameString,           // out/optional
  DWORD cchNameString             // in
);
 

Parameters

pCertContext

A pointer to the specified certificate context to be converted.

dwType

CERT_NAME_EMAIL_TYPE

If the certificate has a Subject Alternative Name extension (for issuer, Issuer Alternative Name), searches for first rfc822Name choice. If the rfc822Name choice isn't found in the extension, searches the Subject Name field for the Email OID, "1.2.840.113549.1.9.1". If the rfc822Name or Email OID is found, returns the string. Otherwise, returns an empty string (returned character count is 1). pvTypePara not used and should be set to NULL.

CERT_NAME_RDN_TYPE

Converts the Subject Name blob by calling CertNameToStr. pvTypePara points to a DWORD containing the dwStrType passed to CertNameToStr. If the Subject Name field is empty and the certificate has a Subject Alternative Name extension, searches for and converts the first directory Name choice from CertNameToStr.

CERT_NAME_ATTR_TYPE

pvTypePara points to the Object Identifier specifying the name attribute to be returned. For example, to get the CN, pvTypePara = szOID_COMMON_NAME ("2.5.4.3"). Searches the Subject Name field for the attribute. If the Subject Name field is empty and the certificate has a Subject Alternative Name extension, checks for the first directoryName choice and searches it.

CERT_NAME_SIMPLE_DISPLAY_TYPE

Iterates through the following list of name attributes and searches the Subject Name and then the Subject Alternative Name extension for the first occurrence of:

szOID_COMMON_NAME ("2.5.4.3")

szOID_ORGANIZATIONAL_UNIT_NAME ("2.5.4.11")

szOID_ORGANIZATION_NAME ("2.5.4.10")

szOID_RSA_emailAddr ("1.2.840.113549.1.9.1")

pvTypePara not used and should be set to NULL.

If none of the above attributes is found, then searches the Subject Alternative Name extension for a rfc822Name choice. If still no match, then, returns the first attribute. Note, like CERT_NAME_ATTR_TYPE, searches the RDNs in reverse order.

dwFlags

CERT_NAME_ISSUER_FLAG

If this flag is set, gets the issuer's name. Otherwise, gets the subject's name.

CERT_NAME_DISABLE_IE4_UTF8_FLAG

By default, CERT_RDN_T61_STRING encoded values are initially decoded as UTF8. If the UTF8 decoding fails, then the value is decoded as 8 bit characters. If this flag is set, skips the initial attempt to decode the value as UTF8, and decodes the value as 8 bit characters.

pvTypePara

Pointer to the a DWORD containing the dwStrType, or Object Identifier specifying the name attribute. See dwType.

pszNameString

Address for the returned string. If pszNameString != NULL && cchNameString != 0, returned pszNameString is always NULL terminated.

cchNameString

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 pszNameString is NULL or cchNameString is zero, returns the required size of the destination string (including the terminating null character). If the specified name type isn't found, returns an empty string with a returned character count of 1.

Example

// EXAMPLE CODE FOR USING CertGetNameString().
// Assume that a pointer to the certificate (pCertContext) is already
// known.
// Set up the variables.
PCCERT_CONTEXT pCertContext;  // Pointer to the specified certificate
                              //   Initialized elsewhere
DWORD dwType = CERT_NAME_EMAIL_TYPE;
                              // Type of CERT_NAME
DWORD dwFlags = CERT_NAME_ISSUER_FLAG;
                              // Flag is set. Get the issuer's name
void *pvTypePara;             // Pointer to the a DWORD containing the
                              //   dwStrType, or Object Identifier
LPTSTR pszNameString;         // Pointer to the name string
DWORD cchNameString;          // # of characters converted-
                              //   including the terminating null
DWORD dwResult;               // Returns # of characters (including 
                              //   the terminating NULL).

// Function call to CertGetNameString to get the required size
// of the destination string
dwResult= CertGetNameString(
            pCertContext,     // in
            CERT_NAME_EMAIL_TYPE,
                              // in - dwType
            CERT_NAME_ISSUER_FLAG,
                              // in - dwFlags to get the issuer's
                              //   name in lieu of the subject's name
            NULL,             // in - pvTypePara is set to NULL as 
                              //   this is CERT_NAME_EMAIL_TYPE
            NULL,             // out, optional - pszNameString
                              //   set to NULL to get the required
                              //   size of the destination string
            0);               // in - cchNameString set to 0 to get
                              //   get the required size of the
                              //   destination string

cout<< "CertGetNameString returned a length of;"<< endl
    << "dwResult = "<< dwResult<< endl<< endl;
 

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later. Available also in IE 3.02 and later.
  Windows: Requires Windows 98 (or Windows 95 with IE 3.02 or later).
  Windows CE: Unsupported.
  Header: Declared in wincrypt.h.
  Import Library: Use crypt32.lib.
  Unicode: Defined as Unicode and ANSI prototypes.