CertGetNameStringA 函数 (wincrypt.h)

  • 项目

CertGetNameString 函数从证书CERT_CONTEXT结构中获取使用者或颁发者名称，并将其转换为以 null 结尾的字符串。

语法

DWORD CertGetNameStringA(
  [in]  PCCERT_CONTEXT pCertContext,
  [in]  DWORD          dwType,
  [in]  DWORD          dwFlags,
  [in]  void           *pvTypePara,
  [out] LPSTR          pszNameString,
  [in]  DWORD          cchNameString
);

参数

[in] pCertContext

指向CERT_CONTEXT证书上下文 的 指针，其中包含要转换的使用者和颁发者名称。

[in] dwType

指示如何查找名称以及如何设置输出格式的 DWORD。

值 含义
CERT_NAME_EMAIL_TYPE
1
 如果证书具有使用者可选名称扩展或颁发者可选名称，请使用第一个 rfc822Name 选项。 如果在扩展中找不到 rfc822Name 选项，请使用Email OID 的“使用者名称”字段。 如果找到 rfc822Name 或 Email OID， 请使用 字符串。 否则， 返回空字符串， (返回的字符计数为 1) 。 不使用 pvTypePara，并且设置为 NULL。
CERT_NAME_RDN_TYPE
2
 通过调用 CertNameToStr 转换使用者名称 BLOB。 pvTypePara 指向包含传递到 CertNameToStrStr 的 dwStrType 的 DWORD。 如果“使用者名称”字段为空，并且证书具有使用者可选名称扩展名，请使用 CertNameToStr 中的第一个目录名称选项。
CERT_NAME_ATTR_TYPE
3
 pvTypePara 指向对象 标识符 (OID) 指定要返回的名称属性。 例如，如果 pvTypePara szOID_COMMON_NAME， 则使用“使用者名称”成员。 如果使用者名称成员为空，并且证书具有使用者可选名称扩展，请使用第一个 directoryName 选项。
CERT_NAME_SIMPLE_DISPLAY_TYPE
4
 循环访问以下名称属性列表，并将使用者名称或使用者可选名称扩展用于第一个匹配项：szOID_COMMON_NAME、szOID_ORGANIZATIONAL_UNIT_NAME、szOID_ORGANIZATION_NAME或szOID_RSA_emailAddr。

如果未找到其中一个属性，则对 rfc822Name 选项使用使用者可选名称扩展。 如果仍然没有匹配项，请使用第一个属性。

不使用 pvTypePara，并且设置为 NULL。
CERT_NAME_FRIENDLY_DISPLAY_TYPE
5
 检查证书中是否有CERT_FRIENDLY_NAME_PROP_ID属性。 如果证书具有此属性，则返回该属性。 如果证书没有 属性，则返回CERT_NAME_SIMPLE_DISPLAY_TYPE。
CERT_NAME_DNS_TYPE
6
 如果证书具有颁发者的使用者可选名称扩展（颁发者可选名称），请搜索第一个 DNSName 选项。

如果在扩展中找不到 DNSName 选项，请在“使用者名称”字段中搜索 CN OID“2.5.4.3”。

如果找到 DNSName 或 CN OID，则返回字符串。 否则，返回一个空字符串。
CERT_NAME_URL_TYPE
7
 如果证书具有颁发者的使用者可选名称扩展，则“颁发者可选名称”，请搜索第一个 URL 选项。 如果找到 URL 选项，则返回字符串。 否则，返回一个空字符串。
CERT_NAME_UPN_TYPE
8
 如果证书具有使用者可选名称扩展，请搜索“其他名称”选项，查找 pszObjId == szOID_NT_PRINCIPAL_NAME， (“1.3.6.1.4.1.311.20.2.3”) 。

如果找到 UPN OID，请将 BLOB 解码为X509_UNICODE_ANY_STRING并返回解码的字符串。 否则，返回一个空字符串。

[in] dwFlags

指示所需的处理类型。

值 含义
CERT_NAME_ISSUER_FLAG
0x1
 获取颁发者的名称。 如果未设置，则获取使用者的名称。
CERT_NAME_DISABLE_IE4_UTF8_FLAG
0x00010000
 跳过默认的初始尝试将值解码为 UTF8，并将解码为 8 位字符。
CERT_NAME_SEARCH_ALL_NAMES_FLAG
0x2
 如果 dwType 参数设置为 CERT_NAME_DNS_TYPE，则返回指定 DNS 值的所有适用名称。 如果没有 DNS 名称，但主题中有 CN 组件，则改为返回 CN。 如果存在 CN 和 DNS 名称，则仅返回 DNS 名称。 这会模拟 SSL 链生成策略。 如果为 除 CERT_NAME_DNS_TYPE 以外的名称类型设置此标志，此函数将返回以 null 结尾的空字符串。

Windows 8 和 Windows Server 2012： 开始支持此标志。
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 此标志允许根据 dwType 参数值将 IA5String 字符串解码为 Unicode 字符串值，如下所示：
  • CERT_NAME_EMAIL_TYPE：如果电子邮件地址的主机名部分包含 Punycode 编码 的 IA5String 组件，则会将其转换为 Unicode 等效组件。
  • CERT_NAME_SIMPLE_DISPLAY_TYPE：如果证书返回了使用者名称 szOID_RSA_emailAddr 或使用者可选名称中的 rfc822Name，并且电子邮件地址 a 的主机名部分包含 Punycode 编码 的 IA5String 组件，则会将其转换为 Unicode 等效项。
  • CERT_NAME_DNS_TYPE：如果证书具有具有 DNSName 选项的颁发者可选名称，并且电子邮件地址 a 的主机名部分包含 Punycode 编码 的 IA5String 组件，则会将其转换为 Unicode 等效项。
  • CERT_NAME_URL_TYPE：对 URI 进行解码和转义。 如果 URI 的服务器主机名包含 Punycode 编码 的 IA5String 组件，则主机名字符串将转换为 Unicode 等效项。
Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支持此值。

[in] pvTypePara

指向包含 dwStrType 的 DWORD 或对象标识符的指针， (OID) 指定 name 属性。 指向的类型由 dwType 的值确定。

[out] pszNameString

指向用于接收返回字符串的已分配缓冲区的指针。 如果 pszNameString 不为 NULL 且 cchNameString 不为零， 则 pszNameString 为 以 null 结尾的字符串。

如果在 dwFlags 参数中指定了CERT_NAME_SEARCH_ALL_NAMES_FLAG，并在 dwType 参数中设置了CERT_NAME_DNS_TYPE，则返回的字符串将包含所有适用的 DNS 名称。 输出字符串中的每个字符串都以 null 结尾，最后一个字符串将以双 null 结尾。 如果未找到 DNS 名称，则返回一个以 null 结尾的空字符串。

[in] cchNameString

为返回的字符串分配的大小（以字符为单位）。 大小必须包含终止 NULL 字符。

返回值

返回转换的字符数，包括终止零字符。 如果 pszNameString 为 NULL 或 cchNameString 为零，则 返回目标字符串的所需大小 (包括终止 NULL 字符) 。 如果未找到指定的名称类型，则 返回以 null 结尾的空字符串，其返回的字符计数为 1。

注解

注意

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

要求

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

另请参阅

数据转换函数