CertNameToStr

The CertNameToStr function converts a certificate name blob to a zero-terminated character string.

The string representation of distinguished names specified in RFC 1779 is adhered to. Deviations were made from RFC 1779 by double quoting embedded quotes, quoting empty strings, and not quoting strings containing consecutive spaces. RDN values of type CERT_RDN_ENCODED_BLOB or CERT_RDN_OCTET_STRING are formatted in hexadecimal (For example,#0A56CF).

#include <wincrypt.h>
DWORD WINAPI CertNameToStr(
  DWORD dwCertEncodingType,  // in
  PCERT_NAME_BLOB pName,     // in
  DWORD dwStrType,           // in
  LPTSTR pszNameString,      // out, optional
  DWORD cszNameString        // in
);

Parameters

dwCertEncodingType

The type of encoding used on the certificate. Currently defined certificate encoding types are shown in the following table:

Encoding type	Value
X509_ASN_ENCODING	0x00000001

pName

A pointer to the CERT_NAME_BLOB to be converted. See BLOB Structure.

dwStrType

Specifies the returned string type desired. The possible types are as follows.

CERT_SIMPLE_NAME_STR

The Object Identifiers are discarded. CERT_RDN entries are separated by ", ". Multiple attributes per CERT_RDN are separated by " + ". For example: Microsoft, Kim Abercrombie + Programmer.

CERT_OID_NAME_STR

The Object Identifiers are included with a "=" separator from their attribute value. CERT_RDN entries are separated by ", ". Multiple attributes per CERT_RDN are separated by "+ ". For example: 2.5.4.11=Microsoft, 2.5.4.3= Kim Abercrombie + 2.5.4.12=Programmer.

CERT_X500_NAME_STR

The Object Identifiers are converted to their X500 key name. Otherwise, same as CERT_OID_NAME_STR. If the Object Identifier doesn't have a corresponding X500 name, then, the Object Identifier is used with an "OID." prefix. For example: OU=Microsoft, CN=Kim Abercrombie + T=Programmer, OID.1.2.3.4.5.6=Unknown.

Quote the RDN value if it contains leading or trailing white space or one of the following characters: ",", "+", "=", """, "\n", "<", ">", "#" or ";". The quoting character is ". If the RDN Value contains a " it is double quoted (""). For example:

OU=" Microsoft", CN="Joe ""Cool""" + T="Programmer, Manager"

CERT_NAME_STR_SEMICOLON_FLAG

This flag can be combined with a bitwise OR operation into dwStrType to replace the ", " separator with a "; " separator.

CERT_NAME_STR_CRLF_FLAG

This flag can be combined with a bitwise OR operation into dwStrType to replace the ", " separator with a "\r\n" separator.

CERT_NAME_STR_NO_PLUS_FLAG

This flag can be combined with a bitwise OR operation into dwStrType to replace the " + " separator with a single space, " ".

CERT_NAME_STR_NO_QUOTING_FLAG

This flag can be combined with a bitwise OR operation into dwStrType to inhibit the above quoting.

CERT_NAME_STR_REVERSE-FLAG

This flag can be combined with a bitwise OR operation into dwStrType to specify that the order of the RDNs is to be reversed before converting to the string.

A reason for using this flag is that the names as they occur in the RDN are reversed from the typical manner in which they are displayed.

For example, an RDN in a certificate might look as follows:

Issuer::

[0,0] 2.5.4.7 (L) Internet

[1,0] 2.5.4.10 (O) VeriSign, Inc.

[2,0] 2.5.4.11 (OU) VeriSign Individual Software Publishers CA

It would be displayed as an X500 name string as follows:

<L=Internet, O="VeriSign, Inc.", OU=VeriSign Individual Software Publishers CA>

To interoperate with LDAP and the RFC standards, the displayed X500 name string should be reversed, by specifying CERT_NAME_STR_REVERSE-FLAG, and it would then be displayed as follows:

<OU=VeriSign Individual Software Publishers CA, O="VeriSign, Inc.", L=Internet>

CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG

This flag can be combined with a bitwise OR operation into dwStrType to select the encoded value type. If this flag is set, and if all the UNICODE characters are <= 0xFF, the CERT_RDN_T61_STRING encoded value type is used instead of the CERT_RDN_UNICODE_STRING.

pszNameString

The address for the returned string.

cszNameString

The 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 cszNameString is zero, returns the required size of the destination string.

Remarks

If pszNameString is not NULL and cszNameString is not zero, the returned pszNameString is always zero terminated.

Example

See Certificate Management Example Code.

QuickInfo