Export (0) Print
Expand All
Expand Minimize

CertNameToStr function

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 WINAPI CertNameToStr(
  _In_   DWORD dwCertEncodingType,
  _In_   PCERT_NAME_BLOB pName,
  _In_   DWORD dwStrType,
  _Out_  LPTSTR psz,
  _In_   DWORD csz
);

Parameters

dwCertEncodingType [in]

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.

ValueMeaning
X509_ASN_ENCODING
1 (0x1)

Specifies X.509 certificate encoding.

 

pName [in]

A pointer to the CERT_NAME_BLOB structure to be converted.

dwStrType [in]

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.

ValueMeaning
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.

ValueMeaning
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.

 

psz [out]

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

csz [in]

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 (“S”).

In addition, the following X.500 key names are not mentioned in RFC 1779, but may be returned by this API:

KeyObject 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.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Crypt32.lib

DLL

Crypt32.dll

Unicode and ANSI names

CertNameToStrW (Unicode) and CertNameToStrA (ANSI)

See also

Data Conversion Functions
CertRDNValueToStr
CertStrToName

 

 

Community Additions

ADD
Show:
© 2014 Microsoft