CertNameToStrW function (wincrypt.h)
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 CertNameToStrW(
[in] DWORD dwCertEncodingType,
[in] PCERT_NAME_BLOB pName,
[in] DWORD dwStrType,
[out] LPWSTR 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 |
|---|---|
|
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 |
|---|---|
|
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. |
|
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 (+ ). |
|
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:
|
The following options can also be combined with the value above to specify additional options for the string.
| Value | Meaning |
|---|---|
|
Replace the comma followed by a space (, ) separator with a semicolon followed by a space (; ) separator. |
|
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. |
|
Replace the plus sign enclosed within spaces ( + ) separator with a single space separator. |
|
Disable quoting. |
|
The order of the RDNs in the distinguished name string is reversed after decoding. This flag is not set by default. |
|
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. |
|
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").
| 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 |