Share via


CertStrToName (Windows Embedded CE 6.0)

1/6/2010

This 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 the CertNameToStr function.

Syntax

BOOL WINAPI CertStrToName(
  DWORD dwCertEncodingType,
  LPCTSTR pszX500,
  DWORD dwStrType,
  void* pvReserved,
  BYTE* pbEncoded,
  DWORD* pcbEncoded,
  LPCTSTR* ppszError
);

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.
  • pszX500
    [in] Pointer to the NULL-terminated X500 string to be converted.
  • dwStrType
    [in] Specifies the type of the input string. The following table shows the possible types of input strings for the dwStrType parameter.

    String type Description

    CERT_OID_NAME_STR

    Default. Input can contain a case-insensitive X500 key (CN=), a case-insensitive OID. prefixed object identifier (OID.1.2.3.4.5.6=), or an object identifier (OID).

    If no flags are combined with a bitwise OR operation into the dwStrType parameter, the input is allowed to contain "," or ";" as RDN separators and "+" as the multiple RDN value separator.

    Quoting is supported. A quote can be included in a quoted value by double quoting, for example (CN="Bob ""Gage"""). A value starting with a "#" is treated as ASCII hex and converted to a CERT_RDN_OCTET_STRING. Embedded white space is skipped (1.2.3 = # AB CD 01 is the same as 1.2.3=#ABCD01).

    White space surrounding the keys, object identifiers, and values is removed.

    CERT_X500_NAME_STR

    Same as CERT_OID_NAME_STR.

    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

    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

    Not supported.

    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.

    CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG

    Can be combined with other dwStrType values to select the CERT_RDN_T61_STRING encoded value type instead of CERT_RDN_UNICODE_STRING. Can be used if all the UNICODE characters are less than or equal to 0xFF.

    CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG

    Can be combined with other dwStrType values to select the CERT_RDN_UTF8_STRING encoded value type instead of CERT_RDN_UNICODE_STRING.

    The following table shows the X500 keys that are supported.

    Key Object identifier RDN value type

    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

    IA5, UTF8

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

    A, B, ..., Z

    a, b, ..., z

    0, 1, ..., 9

    (space) ' ( ) +, - . / : = ?

  • pvReserved
    [in] Reserved for future use and must be set to NULL.
  • pbEncoded
    [out] Pointer to a buffer to receive the encoded structure.

    This parameter can be NULL to set the size of the key usage for memory allocation purposes.

  • pcbEncoded
    [in, out] On input, pointer to a DWORD to specify the size, in bytes, of the buffer pointed to by the pbEncoded parameter. On output, the DWORD contains the number of bytes stored or to be stored in the buffer.
  • ppszError
    [out] Optional. Pointer to a pointer to receive an error indication about an invalid input string.

    If the input string is invalid, the ppszError parameter 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.

    The ppszError parameter can be set to NULL by the application not interested in receiving a pointer to any invalid character sequence found.

    The ppszError parameter 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 Value

If the function succeeds, the return value is nonzero, or TRUE.

If the function fails, the return value is zero, or FALSE.

For extended error information, call the GetLastError function.

Remarks

The T61 types are UTF-8 encoded.

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

See Also

Reference

Certificates Functions
CertNameToStr