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 中包含的 消息编码类型 标识符。
此参数可以是以下当前定义的证书编码类型。
价值 | 意义 |
---|---|
|
指定 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 相同。
将忽略将键、对象标识符和值括起来的空格。
此参数可以是下列值之一。
价值 | 意义 |
---|---|
|
不支持此字符串类型。 |
|
验证是否支持字符串类型。 该字符串可以是 对象标识符(OID)或 X.500 名称。 |
|
与CERT_OID_NAME_STR相同。 验证是否支持字符串类型。 该字符串可以是 对象标识符(OID)或 X.500 名称。 |
还可以将以下选项与上述值组合在一起,以指定字符串的其他选项。
价值 | 意义 |
---|---|
|
仅支持逗号 (,)作为 RDN 分隔符。 |
|
仅支持分号(;)作为 RDN 分隔符)。 |
|
仅支持反斜杠 r (\r) 或反斜杠 n (\n) 作为 RDN 分隔符。 |
|
加号(+)被忽略为分隔符,不支持每个 RDN 的多个值。 |
|
不支持引用。 |
|
在编码之前,将反转具有可分辨名称的 RDN 的顺序。 默认情况下不设置此标志。 |
|
使用 CERT_RDN_T61_STRING 编码值类型,而不是 CERT_RDN_UNICODE_STRING。 如果所有 Unicode 字符都小于或等于0xFF,则可以使用此标志。 |
|
使用 CERT_RDN_UTF8_STRING 编码值类型,而不是 CERT_RDN_UNICODE_STRING。 |
|
强制 X.500 键编码为 UTF-8 (CERT_RDN_UTF8_STRING) 字符串,而不是可打印的 Unicode (CERT_RDN_PRINTABLE_STRING) 字符串。 这是从 Windows Server 2003 开始的Microsoft证书颁发机构的默认值。 |
|
防止强制使用 UTF-8 (CERT_RDN_UTF8_STRING) 对可打印 Unicode (CERT_RDN_PRINTABLE_STRING) X.500 密钥进行编码。 用于在设置CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG时将 X.500 键编码为 Unicode 值。 |
|
如果字符串包含电子邮件 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 |