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 中包含的消息编码类型标识符。

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

Value 含义
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 名称。
 

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

Value 含义
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) 字符串。 这是从 Windows Server 2003 开始的 Microsoft 证书颁发机构的默认值。
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

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

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

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

[in, out] pcbEncoded

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

如果 pbEncodedNULL则 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

 

如果允许可打印或 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

检索未知长度的数据