Edit

CertNameToStrA function (wincrypt.h)

  • Article

The CertNameToStr function converts an encoded name in a CERT_NAME_BLOB structure to a null-terminated character string.

The string representation follows the distinguished name specifications in RFC 1779. The exceptions to this rule are listed in the Remarks section, below.

Syntax

DWORD CertNameToStrA(
  [in]  DWORD           dwCertEncodingType,
  [in]  PCERT_NAME_BLOB pName,
  [in]  DWORD           dwStrType,
  [out] LPSTR           psz,
  [in]  DWORD           csz
);

Parameters

[in] dwCertEncodingType

The certificate encoding type that was used to encode the name. The message encoding type identifier, contained in the high WORD of this value, is ignored by this function.

This parameter can be the following currently defined certificate encoding type.

Value Meaning
X509_ASN_ENCODING
1 (0x1)
 Specifies X.509 certificate encoding.

[in] pName

A pointer to the CERT_NAME_BLOB structure to be converted.

[in] dwStrType

This parameter specifies the format of the output string. This parameter also specifies other options for the contents of the string.

This parameter can be one of the following values.

Value Meaning
CERT_SIMPLE_NAME_STR
1
 All object identifiers (OIDs) are discarded. CERT_RDN entries are separated by a comma followed by a space (, ). Multiple attributes in a CERT_RDN are separated by a plus sign enclosed within spaces ( + ), for example, Microsoft, Kim Abercrombie + Programmer.
CERT_OID_NAME_STR
2
 OIDs are included with an equal sign (=) separator from their attribute value. CERT_RDN entries are separated by a comma followed by a space (, ). Multiple attributes in a CERT_RDN are separated by a plus sign followed by a space (+ ).
CERT_X500_NAME_STR
3
 OIDs are converted to their X.500 key names; otherwise, they are the same as CERT_OID_NAME_STR. If an OID does not have a corresponding X.500 name, the OID is used with a prefix of OID.

The RDN value is quoted if it contains leading or trailing white space or one of the following characters:

  • Comma (,)
  • Plus sign (+)
  • Equal sign (=)
  • Inch mark (")
  • Backslash followed by the letter n (\n)
  • Less than sign (<)
  • Greater than sign (>)
  • Number sign (#)
  • Semicolon (;)
The quotation character is an inch mark ("). If the RDN value contains an inch mark, it is enclosed within quotation marks ("").
 

The following options can also be combined with the value above to specify additional options for the string.

Value Meaning
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 Replace the comma followed by a space (, ) separator with a semicolon followed by a space (; ) separator.
CERT_NAME_STR_CRLF_FLAG
0x08000000
 Replace the comma followed by a space (, ) separator with a backslash followed by the letter r followed by a backslash followed by the letter n (\r\n) separator.
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 Replace the plus sign enclosed within spaces ( + ) separator with a single space separator.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 Disable quoting.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 The order of the RDNs in the distinguished name string is reversed after decoding. This flag is not set by default.
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG
0x00010000
 By default, a CERT_RDN_T61_STRING X.500 key string is decoded as UTF8. If UTF8 decoding fails, the X.500 key is decoded as an 8 bit character. Use CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG to skip the initial attempt to decode as UTF8.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 If the name pointed to by the pName parameter contains an email RDN, and the host name portion of the email address contains a Punycode encoded IA5String, the name is converted to the Unicode equivalent.

Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP:  This value is not supported.

[out] psz

A pointer to a character buffer that receives the returned string. The size of this buffer is specified in the csz parameter.

[in] csz

The size, in characters, of the psz buffer. The size must include the terminating null character.

Return value

Returns the number of characters converted, including the terminating null character.

If psz is NULL or csz is zero, returns the required size of the destination string.

Remarks

If psz is not NULL and csz is not zero, the returned psz is always a null-terminated string.

We recommend against using multicomponent RDNs (e.g., CN=James+O=Microsoft) to avoid possible ordering problems when decoding occurs. Instead, consider using single valued RDNs (e.g., CN=James, O=Microsoft).

The string representation follows the distinguished name specifications in RFC 1779 except for the deviations described in the following list.

  • Names that contain quotes are enclosed within double quotation marks.
  • Empty strings are enclosed within double quotation marks.
  • Strings that contain consecutive spaces are not enclosed within quotation marks.
  • Relative Distinguished Name (RDN) values of type CERT_RDN_ENCODED_BLOB or CERT_RDN_OCTET_STRING are formatted in hexadecimal.
  • If an OID does not have a corresponding X.500 name, the “OID” prefix is used before OID.
  • RDN values are enclosed with double quotation marks (instead of "\") if they contain leading white space, trailing white space, or one of the following characters:
    • Comma (,)
    • Plus sign (+)
    • Equal sign (=)
    • Inch mark (")
    • Backslash (/)
    • Less than sign (<)
    • Greater than sign (>)
    • Number sign (#)
    • Semicolon (;)
  • The X.500 key name for stateOrProvinceName (2.5.4.8) OID is "S". This value is different from the RFC 1779 X.500 key name ("ST").
In addition, the following X.500 key names are not mentioned in RFC 1779, but may be returned by this API:
Key Object identifier string
E 1.2.840.113549.1.9.1
T 2.5.4.12
G 2.5.4.42
I 2.5.4.43
SN 2.5.4.4
 

Examples

For an example that uses this function, see

Example C Program: Converting Names from Certificates to ASN.1 and Back.

Note

The wincrypt.h header defines CertNameToStr as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps | UWP apps]
Minimum supported server Windows Server 2003 [desktop apps | UWP apps]
Target Platform Windows
Header wincrypt.h
Library Crypt32.lib
DLL Crypt32.dll

See also

CertRDNValueToStr

CertStrToName

Data Conversion Functions