Expand Minimize
EN
Este conteúdo não está disponível no seu idioma mas aqui tem a versão em inglês.

CertStrToName function

The CertStrToName function converts a null-terminated X.500 string to an encoded certificate name.

Syntax


BOOL WINAPI CertStrToName(
  _In_       DWORD dwCertEncodingType,
  _In_       LPCTSTR pszX500,
  _In_       DWORD dwStrType,
  _In_opt_   void *pvReserved,
  _Out_      BYTE *pbEncoded,
  _Inout_    DWORD *pcbEncoded,
  _Out_opt_  LPCTSTR *ppszError
);

Parameters

dwCertEncodingType [in]

The certificate encoding type that was used to encode the string. 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.

ValueMeaning
X509_ASN_ENCODING
1 (0x1)

Specifies X.509 certificate encoding.

 

pszX500 [in]

A pointer to the null-terminated X.500 string to be converted. The format of this string is specified by the dwStrType parameter.

This string is expected to be formatted the same as the output from the CertNameToStr function.

dwStrType [in]

This parameter specifies the type of the string. This parameter also specifies other options for the contents of the string.

If no flags are combined with the string type specifier, the string can contain a comma (,) or a semicolon (;) as separators in the relative distinguished name (RDN) and a plus sign (+) as the separator in multiple RDN values.

Quotation marks ("") are supported. A quotation can be included in a quoted value by using two sets of quotation marks, for example, CN="User ""one""".

A value that starts with a number sign (#) is treated as ASCII hexadecimal and converted to a CERT_RDN_OCTET_STRING. Embedded white space is ignored. For example, 1.2.3 = # AB CD 01 is the same as 1.2.3=#ABCD01.

White space that surrounds the keys, object identifiers, and values is ignored.

This parameter can be one of the following values.

ValueMeaning
CERT_SIMPLE_NAME_STR
1

This string type is not supported.

CERT_OID_NAME_STR
2

Validates that the string type is supported. The string can be either an object identifier (OID) or an X.500 name.

CERT_X500_NAME_STR
3

Identical to CERT_OID_NAME_STR. Validates that the string type is supported. The string can be either an object identifier (OID) or an X.500 name.

 

The following options can also be combined with the value above to specify additional options for the string.

ValueMeaning
CERT_NAME_STR_COMMA_FLAG
0x04000000

Only a comma (,) is supported as the RDN separator.

CERT_NAME_STR_SEMICOLON_FLAG
0x40000000

Only a semicolon (;) is supported as the RDN separator.

CERT_NAME_STR_CRLF_FLAG
0x08000000

Only a backslash r (\r) or backslash n (\n) is supported as the RDN separator.

CERT_NAME_STR_NO_PLUS_FLAG
0x20000000

The plus sign (+) is ignored as a separator, and multiple values per RDN are not supported.

CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000

Quoting is not supported.

CERT_NAME_STR_REVERSE_FLAG
0x02000000

The order of the RDNs in a distinguished name is reversed before encoding. This flag is not set by default.

CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG
0x00020000

The CERT_RDN_T61_STRING encoded value type is used instead of CERT_RDN_UNICODE_STRING. This flag can be used if all the Unicode characters are less than or equal to 0xFF.

CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG
0x00040000

The CERT_RDN_UTF8_STRING encoded value type is used instead of CERT_RDN_UNICODE_STRING.

CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG
0x00080000

Forces the X.500 key to be encoded as a UTF-8 (CERT_RDN_UTF8_STRING) string rather than as a printable Unicode (CERT_RDN_PRINTABLE_STRING) string. This is the default value for Microsoft certification authorities beginning with Windows Server 2003.

CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG
0x00100000

Prevents forcing a printable Unicode (CERT_RDN_PRINTABLE_STRING) X.500 key to be encoded by using UTF-8 (CERT_RDN_UTF8_STRING). Use to enable encoding of X.500 keys as Unicode values when CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG is set.

CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000

If the string contains an email RDN value, and the email address contains Unicode characters outside of the ASCII character set, the host name portion of the email address is encoded in Punycode. The resultant email address is then encoded as an IA5String string. The Punycode encoding of the host name is performed on a label-by-label basis.

Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP:  This value is not supported.

 

pvReserved [in, optional]

Reserved for future use and must be NULL.

pbEncoded [out]

A pointer to a buffer that receives the encoded structure. The size of this buffer is specified in the pcbEncoded parameter.

This parameter can be NULL to obtain the required size of the buffer for memory allocation purposes. For more information, see Retrieving Data of Unknown Length.

pcbEncoded [in, out]

A pointer to a DWORD that, before calling the function, contains the size, in bytes, of the buffer pointed to by the pbEncoded parameter. When the function returns, the DWORD contains the number of bytes stored in the buffer.

If pbEncoded is NULL, the DWORD receives the size, in bytes, required for the buffer.

ppszError [out, optional]

A pointer to a string pointer that receives additional error information about an input string that is not valid. If the pszX500 string is not valid, ppszError is updated by this function to point to the beginning of the character sequence that is not valid. If no errors are detected in the input string, ppszError is set to NULL.

If this information is not required, pass NULL for this parameter.

This parameter is updated for the following error codes returned from GetLastError.

CRYPT_E_INVALID_X500_STRING
CRYPT_E_INVALID_NUMERIC_STRING
CRYPT_E_INVALID_PRINTABLE_STRING
CRYPT_E_INVALID_IA5_STRING

Return value

Returns nonzero if successful or zero otherwise.

For extended error information, call GetLastError.

Remarks

The following table contains the supported X.500 keys, their corresponding object identifier string, string identifier (from Wincrypt.h), and value types.

KeyObject identifier stringString identifierRDN value types

CN

2.5.4.3

szOID_COMMON_NAME

Printable

T61

L

2.5.4.7

szOID_LOCALITY_NAME

Printable

T61

O

2.5.4.10

szOID_ORGANIZATION_NAME

Printable

T61

OU

2.5.4.11

szOID_ORGANIZATIONAL_UNIT_NAME

Printable

T61

E

Email

1.2.840.113549.1.9.1

szOID_RSA_emailAddr

IA5

C

2.5.4.6

szOID_COUNTRY_NAME

Printable

S

ST

2.5.4.8

szOID_STATE_OR_PROVINCE_NAME

Printable

T61

STREET

2.5.4.9

szOID_STREET_ADDRESS

Printable

T61

T

Title

2.5.4.12

szOID_TITLE

Printable

T61

G

GivenName

2.5.4.42

szOID_GIVEN_NAME

Printable

T61

I

Initials

2.5.4.43

szOID_INITIALS

Printable

T61

SN

2.5.4.4

szOID_SUR_NAME

Printable

T61

DC

0.9.2342.19200300.100.1.25

szOID_DOMAIN_COMPONENT

IA5

UTF8

 

If either Printable or T61 is allowed as the RDN value type for the key, Printable is automatically selected if the name string component is a member of the following character sets:

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

The T61 types are UTF8 encoded.

Examples

For an example that uses this function, see Example C Program: Converting Names from Certificates to ASN.1 and Back.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Crypt32.lib

DLL

Crypt32.dll

Unicode and ANSI names

CertStrToNameW (Unicode) and CertStrToNameA (ANSI)

See also

Data Conversion Functions
Retrieving Data of Unknown Length
CertNameToStr
GetLastError

 

 

Conteúdo da Comunidade

Adicionar
Mostrar:
© 2014 Microsoft