CertStrToNameA 函数 (wincrypt.h)

  • 项目

CertStrToName 函数将以 null 结尾的 X.500 字符串转换为编码的证书名称。

语法

BOOL CertStrToNameA(
  [in]            DWORD  dwCertEncodingType,
  [in]            LPCSTR pszX500,
  [in]            DWORD  dwStrType,
  [in, optional]  void   *pvReserved,
  [out]           BYTE   *pbEncoded,
  [in, out]       DWORD  *pcbEncoded,
  [out, optional] LPCSTR *ppszError
);

参数

[in] dwCertEncodingType

用于 对 字符串进行编码的证书编码类型。 此函数忽略包含在此值的高 WORD 中的消息编码类型标识符。

此参数可以是以下当前定义的证书编码类型。

值 含义
X509_ASN_ENCODING
1 (0x1)
 指定 X.509 证书编码。

[in] pszX500

指向要转换的以 null 结尾的 X.500 字符串的指针。 此字符串的格式由 dwStrType 参数指定。

此字符串的格式应与 CertNameToStr 函数的输出相同。

[in] dwStrType

此参数指定字符串的类型。 此参数还指定字符串内容的其他选项。

如果没有标志与字符串类型说明符结合使用，则字符串可以包含逗号 (，) 或分号 (;) 作为 相对可分辨名称 的分隔符 (RDN) ，加号 (+) 作为多个 RDN 值中的分隔符。

支持引号 (“”) 。 可以使用两组引号（例如 CN=“User ”“one”）将引号包含在带引号的值中。

以数字符号 (#) 开头的值被视为 ASCII 十六进制值，并转换为 CERT_RDN_OCTET_STRING。 将忽略嵌入的空格。 例如，1.2.3 = # AB CD 01 与 1.2.3=#ABCD01 相同。

忽略键、对象标识符和值周围的空格。

此参数的取值可为下列值之一：

值 含义
CERT_SIMPLE_NAME_STR
1
 不支持此字符串类型。
CERT_OID_NAME_STR
2
 验证字符串类型是否受支持。 字符串可以是 OID) (对象标识符 ，也可以是 X.500 名称。
CERT_X500_NAME_STR
3
 与 CERT_OID_NAME_STR 相同。 验证字符串类型是否受支持。 字符串可以是 OID) (对象标识符 ，也可以是 X.500 名称。
 

还可以将以下选项与上述值组合在一起，为字符串指定其他选项。

值 含义
CERT_NAME_STR_COMMA_FLAG
0x04000000
 仅支持逗号 (，) 作为 RDN 分隔符。
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 仅支持将分号 (;) 作为 RDN 分隔符。
CERT_NAME_STR_CRLF_FLAG
0x08000000
 RDN 分隔符仅支持反斜杠 r (\r) 或反斜杠 n (\n) 。
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 加号 (+) 作为分隔符被忽略，不支持每个 RDN 多个值。
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 不支持引用。
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 在编码之前，可分辨名称中的 RDN 顺序将反转。 默认情况下不设置此标志。
CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG
0x00020000
 使用 CERT_RDN_T61_STRING 编码的值类型，而不是 CERT_RDN_UNICODE_STRING。 如果所有 Unicode 字符都小于或等于 0xFF，则可以使用此标志。
CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG
0x00040000
 使用 CERT_RDN_UTF8_STRING 编码的值类型，而不是 CERT_RDN_UNICODE_STRING。
CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG
0x00080000
 强制将 X.500 密钥编码为 UTF-8 (CERT_RDN_UTF8_STRING) 字符串，而不是可打印的 Unicode (CERT_RDN_PRINTABLE_STRING) 字符串。 这是 Microsoft 证书颁发机构从 Windows Server 2003 开始的默认值。
CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG
0x00100000
 防止使用 UTF-8 (CERT_RDN_UTF8_STRING) 强制可打印 Unicode (CERT_RDN_PRINTABLE_STRING) X.500 密钥进行编码。 在设置 CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG 时，使用 启用将 X.500 键编码为 Unicode 值。
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 如果字符串包含电子邮件 RDN 值，并且电子邮件地址包含 ASCII 字符集外部的 Unicode 字符，则电子邮件地址的主机名部分以 Punycode 编码。 然后，生成的电子邮件地址将编码为 IA5String 字符串。 主机名的 Punycode 编码是逐个标签执行的。

Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支持此值。

[in, optional] pvReserved

保留供将来使用，必须为 NULL。

[out] pbEncoded

指向接收编码结构的缓冲区的指针。

此缓冲区的大小在 板Encoded 参数中指定。

此参数可以为 NULL ，以获取内存分配所需的缓冲区大小。 有关详细信息，请参阅 检索长度未知的数据。

[in, out] pcbEncoded

指向 DWORD 的指针，在调用函数之前，该指针包含 pbEncoded 参数指向的缓冲区的大小（以字节为单位）。 函数返回时， DWORD 包含缓冲区中存储的字节数。

如果 pbEncoded 为 NULL， 则 DWORD 接收缓冲区所需的大小（以字节为单位）。

[out, optional] ppszError

指向字符串指针的指针，该指针接收有关无效输入字符串的其他错误信息。

如果 pszX500 字符串无效， 则此函数将 ppszError 更新为指向无效字符序列的开头。 如果输入字符串中未检测到错误， 则 ppszError 设置为 NULL。

如果不需要此信息，请为此参数传递 NULL 。

此参数针对从 GetLastError 返回的以下错误代码进行了更新。

CRYPT_E_INVALID_X500_STRING

CRYPT_E_INVALID_NUMERIC_STRING

CRYPT_E_INVALID_PRINTABLE_STRING

CRYPT_E_INVALID_IA5_STRING

返回值

如果成功，则返回非零值，否则返回零。

有关扩展的错误信息，请调用 GetLastError。

注解

下表包含支持的 X.500 键、其相应的对象标识符字符串、来自 Wincrypt.h) 的字符串标识符 (以及值类型。

密钥 对象标识符字符串 字符串标识符 RDN 值类型
CN 2.5.4.3 szOID_COMMON_NAME 可打印

T61
L 2.5.4.7 szOID_LOCALITY_NAME 可打印

T61
O 2.5.4.10 szOID_ORGANIZATION_NAME 可打印

T61
OU 2.5.4.11 szOID_ORGANIZATIONAL_UNIT_NAME 可打印

T61
E

电子邮件

 1.2.840.113549.1.9.1 szOID_RSA_emailAddr IA5
C 2.5.4.6 szOID_COUNTRY_NAME 可打印
S

ST

 2.5.4.8 szOID_STATE_OR_PROVINCE_NAME 可打印

T61
STREET 2.5.4.9 szOID_STREET_ADDRESS 可打印

T61
T

标题

 2.5.4.12 szOID_TITLE 可打印

T61
G

GivenName

 2.5.4.42 szOID_GIVEN_NAME 可打印

T61
I

Initials

 2.5.4.43 szOID_INITIALS 可打印

T61
SN 2.5.4.4 szOID_SUR_NAME 可打印

T61
DC 0.9.2342.19200300.100.1.25 szOID_DOMAIN_COMPONENT IA5

UTF8
 

如果允许 Printable 或 T61 作为键的 RDN 值类型，则如果名称字符串组件是以下字符集的成员，则会自动选择 Printable：

  • A、B、...、Z
  • a、b、...、z
  • 0, 1, ..., 9
  • (空间) ' ( ) + ， - 。 / : = ?

T61 类型采用 UTF8 编码。

示例

有关使用此函数的示例，请参阅 示例 C 程序：将名称从证书转换为 ASN.1 和 Back。

注意

wincrypt.h 标头将 CertStrToName 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 Windows XP [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2003 [桌面应用 | UWP 应用]
目标平台 Windows
标头 wincrypt.h
Library Crypt32.lib
DLL Crypt32.dll

另请参阅

CertNameToStr

数据转换函数

GetLastError

检索未知长度的数据