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
仅支持反斜杠 r (\r) 或反斜杠 n (\n) 作为 RDN 分隔符。
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 值类型
快递 之 家 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

2.5.4.8 szOID_STATE_OR_PROVINCE_NAME 打印

T61

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

缩写

2.5.4.43 szOID_INITIALS 打印

T61

2.5.4.4 szOID_SUR_NAME 打印

T61

直流 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 应用]
目标平台 窗户
标头 wincrypt.h
Crypt32.lib
DLL Crypt32.dll

另请参阅

CertNameToStr

数据转换函数

GetLastError

检索未知长度的数据