Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function converts the name in a CERT_NAME_BLOBstructure 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_BLOBstructure 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_RDNstructure are separated by " + ". For example: Microsoft, Kim Abercrombie + Programmer.

CERT_OID_NAME_STR

OIDs are included with a "=" separator from their attribute value. CERT_RDNstructure entries are separated by ", ". Multiple attributes in a CERT_RDNstructure 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 ORoperation into dwStrTypeto replace the ", " separator with a "; " separator.

CERT_NAME_STR_CRLF_FLAG

This flag can be combined with a bitwise ORoperation into dwStrTypeto replace the ", " separator with a "\r\n" separator.

CERT_NAME_STR_NO_PLUS_FLAG

This flag can be combined with a bitwise ORoperation into dwStrTypeto replace the " + " separator with a single space, " ".

CERT_NAME_STR_NO_QUOTING_FLAG

This flag can be combined with a bitwise ORoperation into dwStrTypeto inhibit the above quoting.

CERT_NAME_STR_REVERSE_FLAG

This flag can be combined with a bitwise ORoperation into dwStrTypeto 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 ORoperation into dwStrTypeto 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 pszis NULL or cszis zero, returns the required size of the destination string.

Remarks

If the pszparameter is not NULL and the c sz parameter is not zero, the returned pszparameter 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

Header wincrypt.h
Library crypt32.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also