CertNameToStr

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function converts the name in a CERT_NAME_BLOB structure to a NULL-terminated character string. The string representation follows distinguished name specifications in RFC 1779 except for the following deviations:

• Embedded quotes are double-quoted.
• Empty strings are quoted.
• Strings containing consecutive spaces are not quoted.
• RDN values of type CERT_RDN_ENCODED_BLOB or CERT_RDN_OCTET_STRING are formatted in hexadecimal.

Syntax

DWORD WINAPI CertNameToStr(
  DWORD dwCertEncodingType,
  PCERT_NAME_BLOB pName,
  DWORD dwStrType,
  LPTSTR psz,
  DWORD csz
);

Parameters

• dwCertEncodingType
  [in] Specifies the encoding type used. Currently, only X509_ASN_ENCODING is used; however, additional encoding types may be added in the future.

• pName
  [in] Pointer to the CERT_NAME_BLOB structure to be converted.

• dwStrType
  [in] Specifies the desired returned string type. The following table shows the possible string types for this parameter.

  String type code	Description
  CERT_SIMPLE_NAME_STR	Object identifiers (OID) are discarded. CERT_RDN entries are separated by ", ". Multiple attributes in a CERT_RDN structure are separated by " + ". For example: Microsoft, Kim Abercrombie + Programmer.
  CERT_OID_NAME_STR	OIDs are included with a "=" separator from their attribute value. CERT_RDN structure entries are separated by ", ". Multiple attributes in a CERT_RDN structure are separated by "+ ".
  CERT_X500_NAME_STR	OIDs are converted to their X.500 key names. Otherwise, it is the same as CERT_OID_NAME_STR. If an OID does not have a corresponding X.500 name, the OID is used with an "OID." prefix. Quotes 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 ("").
  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. This flag is to reverse the names as they occur in the RDN. To interoperate with LDAP and the RFC standards, the displayed X500 name string is reversed by specifying this flag.
  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 less than or equal to 0xFF, the CERT_RDN_T61_STRING encoded value type is used instead of the CERT_RDN_UNICODE_STRING.

• psz
  [out] Pointer to a buffer to receive the returned string.

• csz
  [in] Size, in characters, allocated for the returned string. 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 the psz parameter is not NULL and the csz parameter is not zero, the returned psz parameter is always a perhaps-empty NULL-terminated string.

The desktop operating system supports the flag PKCS_7_ASN_ENCODING, but Windows Embedded CE does not and ignores the flag when it is specified.

Requirements

See Also

Reference

CertRDNValueToStr
CertStrToName
BLOB (Cryptography)
CERT_RDN