CertNameToStrA 函数 (wincrypt.h)

  • 项目

CertNameToStr 函数将CERT_NAME_BLOB结构中的编码名称转换为以 null 结尾的字符串。

字符串表示形式遵循 RFC 1779 中的可分辨名称规范。 下面的“备注”部分列出了此规则的例外情况。

语法

DWORD CertNameToStrA(
  [in]  DWORD           dwCertEncodingType,
  [in]  PCERT_NAME_BLOB pName,
  [in]  DWORD           dwStrType,
  [out] LPSTR           psz,
  [in]  DWORD           csz
);

参数

[in] dwCertEncodingType

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

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

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

[in] pName

指向要转换 的CERT_NAME_BLOB 结构的指针。

[in] dwStrType

此参数指定输出字符串的格式。 此参数还指定字符串内容的其他选项。

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

值 含义
CERT_SIMPLE_NAME_STR
1
 将丢弃 (OID) 的所有 对象标识符 。 CERT_RDN 条目用逗号分隔，后跟空格 (，) 。 CERT_RDN中的多个属性由包含在空格中的加号分隔 ( + ) ，例如 Microsoft、Kim Abercrombie + 程序员。
CERT_OID_NAME_STR
2
 OID 包含在属性值中的等号 (=) 分隔符。 CERT_RDN 条目用逗号分隔，后跟空格 (，) 。 CERT_RDN中的多个属性用加号分隔，后跟空格 (+ ) 。
CERT_X500_NAME_STR
3
 OID 将转换为其 X.500 密钥名称;否则，它们与 CERT_OID_NAME_STR 相同。 如果 OID 没有相应的 X.500 名称，则 OID 的前缀为 OID。

如果 RDN 值包含前导空格或尾随空格或以下字符之一，则为引号：

  • 逗号 (,)
  • 加号 (+)
  • 等号 (=)
  • 英寸标记 (“)
  • 反斜杠后跟字母 n (\n)
  • 小于符号 (<)
  • 大于符号 (>)
  • 数字符号 (#)
  • 分号 (;)
引号字符是英寸标记 (“) 。 如果 RDN 值包含英寸标记，则将其括在引号 (“”) 中。
 

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

值 含义
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 将逗号后跟空格 (，) 分隔符替换为分号，后跟空格 (;) 分隔符。
CERT_NAME_STR_CRLF_FLAG
0x08000000
 将逗号后跟空格 (，) 分隔符替换为反斜杠，后跟字母 r，后跟反斜杠，后跟字母 n (\r\n) 分隔符。
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 将空格中的加号 ( + ) 分隔符替换为单个空格分隔符。
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 禁用引用。
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 解码后，可分辨名称字符串中 RDN 的顺序将颠倒。 默认情况下不设置此标志。
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG
0x00010000
 默认情况下，CERT_RDN_T61_STRING X.500 密钥字符串被解码为 UTF8。 如果 UTF8 解码失败，X.500 密钥将解码为 8 位字符。 使用 CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG 跳过最初尝试将解码为 UTF8。
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 如果 pName 参数指向的名称包含电子邮件 RDN，并且电子邮件地址的主机名部分包含 Punycode 编码 的 IA5String，则名称将转换为 Unicode 等效项。

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

[out] psz

指向接收返回字符串的字符缓冲区的指针。 此缓冲区的大小在 csz 参数中指定。

[in] csz

psz 缓冲区的大小（以字符为单位）。 大小必须包含终止 null 字符。

返回值

返回转换的字符数，包括终止 null 字符。

如果 psz 为 NULL 或 csz 为零，则返回目标字符串的所需大小。

注解

如果 psz 不为 NULL 且 csz 不为零，则返回的 psz 始终为以 null 结尾的字符串。

建议不要使用多组件 RDN (例如 CN=James+O=Microsoft) ，以避免解码时可能出现的排序问题。 相反，请考虑使用单值 RDN (例如 CN=James、O=Microsoft) 。

字符串表示形式遵循 RFC 1779 中的可分辨名称规范，但以下列表中描述的偏差除外。

  • 包含引号的名称括在双引号内。
  • 空字符串括在双引号内。
  • 包含连续空格的字符串不会用引号引起来。
  • 相对可分辨名称 (RDN ) CERT_RDN_ENCODED_BLOB 或CERT_RDN_OCTET_STRING 类型的值采用十六进制格式。
  • 如果 OID 没有相应的 X.500 名称，则会在 OID 之前使用“OID”前缀。
  • 如果 RDN 值包含前导空格、尾随空格或以下字符之一，则用双引号 (而不是“\”) 括起来：
    • 逗号 (,)
    • 加号 (+)
    • 等号 (=)
    • 英寸标记 (“)
    • 反斜杠 (/)
    • 小于符号 (<)
    • 大于符号 (>)
    • 数字符号 (#)
    • 分号 (;)
  • stateOrProvinceName (2.5.4.8) OID 的 X.500 密钥名称为“S”。 此值不同于 RFC 1779 X.500 密钥名称 (“ST”) 。
此外，RFC 1779 中未提及以下 X.500 密钥名称，但可能由此 API 返回：
键 对象标识符字符串
E 1.2.840.113549.1.9.1
T 2.5.4.12
G 2.5.4.42
I 2.5.4.43
SN 2.5.4.4
 

示例

有关使用此函数的示例，请参阅

示例 C 程序：将名称从证书转换为 ASN.1 和 Back。

注意

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

要求

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

另请参阅

CertRDNValueToStr

CertStrToName

数据转换函数