CertStrToName

The CertStrToName function converts a NULL-terminated X500 string to an encoded certificate name. The input string is expected to be formatted the same as the output from CertNameToStr.

#include <wincrypt.h>
BOOL WINAPI CertStrToName(
  DWORD dwCertEncodingType,   // in
  LPCTSTR pszX500,            // in
  DWORD dwStrType,            // in
  void* pvReserved,           // in, optional
  BYTE* pbEncoded,            // out
  DWORD* pcbEncoded,          // in/out
  LPCTSTR* ppszError          // out, optional
);

Parameters

dwCertEncodingType

The type of encoding used on the certificate. Currently defined certificate encoding types are shown in the following table:

Encoding type	Value
X509_ASN_ENCODING	0x00000001

pszX500

A pointer to the zero-terminated X500 string to be converted.

dwStrType

The type of the input string. The possible types are as follows.

When dwStrType is set to 0, CERT_OID_NAME_STR or CERT_X500_NAME_STR, the input is allowed to contain either a case insensitive X500 key (CN=), case insensitive "OID." prefixed object identifier (OID.1.2.3.4.5.6=) or an object identifier (1.2.3.4=).

If no flags are combined with a bitwise OR operation into dwStrType, then, the input is allowed to contain "," or ";" as RDN separators and "+" as the multiple RDN value separator. Quoting is supported. A quote may be included in a quoted value by double quoting, for example (CN="Joe ""Cool"""). A value starting with a "#" is treated as ascii hex and converted to a CERT_RDN_OCTET_STRING. Embedded whitespace is skipped (1.2.3 = # AB CD 01 is the same as 1.2.3=#ABCD01).

Whitespace surrounding the keys, object identifiers and values are removed.

CERT_NAME_STR_COMMA_FLAG: This flag can be combined with a bitwise OR operation into dwStrType to only allow the "," as the RDN separator.
CERT_NAME_STR_SEMICOLON_FLAG: This flag can be combined with a bitwise OR operation into dwStrType to only allow the ";" as the RDN separator.
CERT_NAME_STR_CRLF_FLAG: This flag can be combined with a bitwise OR operation into dwStrType to only allow "\r" or "\n" as the RDN separator.
CERT_NAME_STR_NO_PLUS_FLAG: This flag can be combined with a bitwise OR operation into dwStrType to ignore "+" as a separator and not allow multiple values per RDN.
CERT_NAME_STR_NO_QUOTING_FLAG: This flag can be combined with a bitwise OR operation into dwStrType to inhibit quoting.
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG: By default, CERT_RDN_T61_STRING encoded values are initially decoded as UTF8. If the UTF8 decoding fails, then the value is decoded as 8 bit characters. This flag can be combined with a bitwise OR operation into dwStrType to skip the initial attempt to decode as UTF8.
CERT_SIMPLE_NAME_STR: This type isn't supported since it doesn't contain any (CN=) type of information.
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 after converting from the string and before encoding. See CertNameToStr for a demonstration of this flags usage.

The following X500 Keys are supported:

Key Object Identifier RDN Value Type(s)

CN szOID_COMMON_NAME Printable, T61

L szOID_LOCALITY_NAME Printable, T61

O szOID_ORGANIZATION_NAME Printable, T61

OU szOID_ORGANIZATIONAL_UNIT_NAME Printable, T61

Email szOID_RSA_emailAddr Only IA5

C szOID_COUNTRY_NAME Only Printable

S szOID_STATE_OR_PROVINCE_NAME Printable, T61

ST szOID_STATE_OR_PROVINCE_NAME Printable, T61

STREET szOID_STREET_ADDRESS Printable, T61

T szOID_TITLE Printable, T61

Title szOID_TITLE Printable, T61

G szOID_GIVEN_NAME Printable, T61

GivenName szOID_GIVEN_NAME Printable, T61

I szOID_INITIALS Printable, T61

Initials szOID_INITIALS Printable, T61

SN szOID_SUR_NAME Printable, T61

DC szOID_DOMAIN_COMPONENT Only IA5

Key	Object Identifier	RDN Value Type(s)
CN	szOID_COMMON_NAME	Printable, T61
L	szOID_LOCALITY_NAME	Printable, T61
O	szOID_ORGANIZATION_NAME	Printable, T61
OU	szOID_ORGANIZATIONAL_UNIT_NAME	Printable, T61
Email	szOID_RSA_emailAddr	Only IA5
C	szOID_COUNTRY_NAME	Only Printable
S	szOID_STATE_OR_PROVINCE_NAME	Printable, T61
ST	szOID_STATE_OR_PROVINCE_NAME	Printable, T61
STREET	szOID_STREET_ADDRESS	Printable, T61
T	szOID_TITLE	Printable, T61
Title	szOID_TITLE	Printable, T61
G	szOID_GIVEN_NAME	Printable, T61
GivenName	szOID_GIVEN_NAME	Printable, T61
I	szOID_INITIALS	Printable, T61
Initials	szOID_INITIALS	Printable, T61
SN	szOID_SUR_NAME	Printable, T61
DC	szOID_DOMAIN_COMPONENT	Only IA5

If either Printable or T61 is allowed as the RDN Value Type for the key (CN=), then Printable is selected if the name string components are restricted to the following character set:

A, B, …, Z
a, b, …, z
0, 1, …, 9
(space) ' ( ) +, - . / : = ?

pvReserved

This parameter is reserved for future use and must be NULL.

pbEncoded

Pointer to a buffer that receives the encoded structure.

This parameter can be NULL to set the size of the key usage for memory allocation purposes. For more information, see the "Common In/Out Parameter Conventions" section at the beginning of this Reference.

pcbEncoded

Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbEncoded parameter. When the function returns, the variable pointed to by the pcbEncoded parameter contains the number of bytes stored in the buffer. This parameter can be NULL, only if pbEncoded is NULL.

ppszError

An application may specify a pointer for ppszError if designed to handle errors caused by invalid input strings.

If the input string is detected to be invalid, *ppszError is updated by this function to point to the beginning of the invalid character sequence. If no errors are detected in the input string, *ppszError is set to NULL.

ppszError can be set to NULL by the application if it is not interested in getting a pointer to the invalid character sequence, should one be found.

*ppszError is updated with a non-NULL pointer for the following errors:

CRYPT_E_INVALID_X500_STRING
CRYPT_E_INVALID_NUMERIC_STRING
CRYPT_E_INVALID_PRINTABLE_STRING
CRYPT_E_INVALID_IA5_STRING

Return Values

Returns TRUE if the input string was successfully parsed and the name was encoded without error. Otherwise, FALSE is returned.

Call GetLastError to see the reason for any failures.

Remarks

The T61 types are UTF-8 encoded.

Example

// EXAMPLE CODE FOR USING CertStrToName().
// Converts a X500 string to an encoded certificate name.
// Assume a pointer to the X500 string is already known.

// Set up the variables.
DWORD dwCertEncodingType = X509_ASN_ENCODING; 
                           // Type of encoding
LPCTSTR pszX500;           // Initialized elsewhere
DWORD dwStrType = 0;       // Type of input string
void * pvReserved = NULL;  // Reserved - set to NULL
BYTE * pbEncoded;          // Pointer to the BYTE blob
DWORD cbEncoded;           // # of bytes of the BYTE blob
LPCTSTR* ppszError;        // Error handling-out, optional
BOOL fResult;              // Returned TRUE if name is encoded
                           //   FALSE if error occurred

// Function called the first time to get
// the size of the structure
fResult = CertStrToName(
            dwCertEncodingType,
            pszX500,
            dwStrType,
            pvReserved,
            pbEncoded,
            &cbEncoded,
            ppszError);

if (!fResult){
 cout<< "First call to CertStrToName failed"<< endl;
}
else {
  cout<< "First call to CertStrToName successful"<< endl;
  pbEncoded = (BYTE*)malloc (cbEncoded);
  cout<< "memory allocated" << endl;
}

// Function call to convert string to name
fResult = CertStrToName(
            dwCertEncodingType,// in - Type of encoding
            pszX500,           // in - Pointer to the X500 string
            dwStrType,         // in - 0 allows case insensitive key
            pvReserved,        // in, optional - must be NULL 
            pbEncoded,         // out - Pointer to the structure
            &cbEncoded,        // in/out - # of bytes in the structure
            ppszError);        // out, optional - Set to NULL- not
                               //   interested in getting a pointer to
                               //   the invalid character sequence

if (!fResult){                 // FALSE
  cout<< "String was not parsed "<< endl
      << "error code = "<< GetLastError ()<< endl;
}
else {                         // TRUE
  cout<< "String was parsed"<< endl
      << "encoded structure = "<< &pbEncoded<< endl
      << "of "<< cbEncoded<< " bytes"<< endl;
}
free (&pbEncoded);

QuickInfo