CertSetCTLContextProperty 函数 (wincrypt.h)

  • 项目

CertSetCTLContextProperty 函数为指定的证书信任列表设置扩展属性 (CTL) 上下文。

语法

BOOL CertSetCTLContextProperty(
  [in] PCCTL_CONTEXT pCtlContext,
  [in] DWORD         dwPropId,
  [in] DWORD         dwFlags,
  [in] const void    *pvData
);

参数

[in] pCtlContext

指向 CTL_CONTEXT 结构的指针。

[in] dwPropId

标识要设置的属性。 dwPropId 的值确定 pvData 参数的类型和内容。 当前定义的标识符及其相关 pvData 类型如下所示。

值 含义
CERT_ARCHIVED_PROP_ID
 pvData 的数据类型：NULL

指示枚举期间跳过证书。 仍可以通过显式搜索操作（例如查找具有特定 哈希 或特定序列号的证书）找到具有此属性集的证书。
CERT_AUTO_ENROLL_PROP_ID
 pvData 的数据类型：指向CRYPT_DATA_BLOB的指针

使用自动注册注册证书后设置的属性。 pvData 指向的CRYPT_DATA_BLOB结构包括证书类型自动注册的以 null 结尾的 Unicode 名称。 对证书自动注册的任何后续调用都会检查此属性，以确定证书是否已注册。
CERT_CTL_USAGE_PROP_ID
 pvData 的数据类型：指向CRYPT_DATA_BLOB的指针

pvData指向包含抽象语法表示法 One (ASN.1) 编码CTL_USAGE结构CRYPT_DATA_BLOB结构。 此结构是使用 CryptEncodeObject 编码的，并设置了X509_ENHANCED_KEY_USAGE值。
CERT_DESCRIPTION_PROP_ID
 pvData 的数据类型：指向CRYPT_DATA_BLOB的指针

由证书 UI 设置和显示的属性。 此属性允许用户描述证书的用法。
CERT_ENHKEY_USAGE_PROP_ID
 pvData 的数据类型：指向CRYPT_DATA_BLOB的指针

包含 ASN.1 编码CERT_ENHKEY_USAGE结构的CRYPT_DATA_BLOB结构。 此结构是使用 CryptEncodeObject 编码的，并设置了X509_ENHANCED_KEY_USAGE值。
CERT_FRIENDLY_NAME_PROP_ID
 pvData 的数据类型：指向CRYPT_DATA_BLOB的指针

CRYPT_DATA_BLOB 结构指定证书的显示名称。
CERT_HASH_PROP_ID
 pvData 的数据类型：指向CRYPT_HASH_BLOB的指针

此属性通过调用 CertGetCertificateContextProperty 隐式设置。
CERT_KEY_CONTEXT_PROP_ID
 pvData 的数据类型：指向CERT_KEY_CONTEXT的指针

CERT_KEY_CONTEXT结构包含 HCRYPTPROV 值和私钥的密钥规范。 有关 hCryptProv 成员和 dwFlags 设置的详细信息，请参阅下文CERT_KEY_PROV_HANDLE_PROP_ID。 请注意，可以为此属性添加更多 CERT_KEY_CONTEXT 结构成员。 如果是这样，将相应地调整 cbSize 成员值。 cbSize 成员必须设置为CERT_KEY_CONTEXT结构的大小
CERT_KEY_IDENTIFIER_PROP_ID
 pvData 的数据类型：指向CRYPT_DATA_BLOB的指针

此属性通常通过调用 CertGetCertificateContextProperty 隐式设置。
CERT_KEY_PROV_HANDLE_PROP_ID
 pvData 的数据类型：指向 HCRYPTPROV 的指针

传递证书私钥的 HCRYPTPROV 句柄。 如果CERT_KEY_CONTEXT结构的 hCryptProv 成员存在，则会更新该成员。 如果不存在，则使用由 CERT_KEY_PROV_INFO_PROP_ID 初始化的 dwKeySpec 创建它。 如果未设置CERT_STORE_NO_CRYPT_RELEASE_FLAG，则当 属性设置为 NULL 或最终释放 CERT_CONTEXT 结构时，将隐式释放 hCryptProv 值。
CERT_KEY_PROV_INFO_PROP_ID
 pvData 的数据类型：指向CRYPT_KEY_PROV_INFO的指针

CRYPT_KEY_PROV_INFO 结构指定证书的私钥。
CERT_KEY_SPEC_PROP_ID
 pvData 的数据类型：指向 DWORD 的指针

DWORD 值指定私钥。 如果CERT_KEY_CONTEXT结构的 dwKeySpec 成员存在，则会更新该成员。 否则，将创建 hCryptProv 设置为零。
CERT_MD5_HASH_PROP_ID
 pvData 的数据类型：指向CRYPT_HASH_BLOB的指针

此属性通过调用 CertGetCertificateContextProperty 隐式设置。
CERT_NEXT_UPDATE_LOCATION_PROP_ID
 pvData 的数据类型：指向CRYPT_DATA_BLOB的指针

CRYPT_DATA_BLOB 结构包含使用 CryptEncodeObject编码的 ASN.1 编码CERT_ALT_NAME_INFO结构，并设置了X509_ALTERNATE_NAME值。 CERT_NEXT_UPDATE_LOCATION_PROP_ID目前仅用于 CTL。
CERT_PVK_FILE_PROP_ID
 pvData 的数据类型：指向CRYPT_DATA_BLOB的指针

CRYPT_DATA_BLOB结构指定包含与证书公钥关联的私钥的文件的名称。 在 CRYPT_DATA_BLOB 结构中， pbData 成员是指向 以 null 结尾的 Unicode、宽字符字符串的指针， cbData 成员指示字符串的长度。
CERT_SHA1_HASH_PROP_ID
 pvData 的数据类型：指向CRYPT_HASH_BLOB的指针

此属性通过调用 CertGetCertificateContextProperty 隐式设置。
CERT_SIGNATURE_HASH_PROP_ID
CRYPT_HASH_BLOB
pvData 的数据类型：指向CRYPT_HASH_BLOB的指针

如果签名哈希不存在，则使用 CryptHashToBeSigned 对其进行计算。 pvData 指向现有或计算的哈希。 通常，对于 SHA，哈希的长度为 20 个字节，MD5 的长度为 16 个字节。
 

通常，仅设置 CERT_NEXT_UPDATE_LOCATION_PROP_ID 属性。

用户可以使用从 CERT_FIRST_USER_PROP_ID 到 CERT_LAST_USER_PROP_ID 的 DWORD 值定义其他 dwPropId 类型。 对于所有用户定义的 dwPropId 类型， pvData 指向编码 CRYPT_DATA_BLOB 结构。

[in] dwFlags

可以为CERT_KEY_PROV_HANDLE_PROP_ID或CERT_KEY_CONTEXT_PROP_ID dwPropId 属性设置CERT_STORE_NO_CRYPT_RELEASE_FLAG。

如果设置了CERT_SET_PROPERTY_IGNORE_PERSIST_ERROR_FLAG值，则忽略任何提供程序写入错误，并始终设置缓存上下文的属性。

如果设置了CERT_SET_PROPERTY_INHIBIT_PERSIST_FLAG，则不会保留任何属性集。

[in] pvData

指向由 dwPropId 中传递的值确定的数据类型的指针。

注意 对于任何 dwPropId，将 pvData 设置为 NULL 会删除 属性。
 

返回值

如果函数成功，则返回值为 TRUE。

如果函数失败，则返回值为 FALSE。 有关扩展的错误信息，请调用 GetLastError。 一个可能的错误代码如下。

返回代码 说明
E_INVALIDARG
 属性标识符无效。 有关详细信息，请参阅 CertSetCertificateContextProperty。

注解

如果属性已存在，则替换其旧值。

示例

请参阅 示例 C 程序：获取和设置证书属性。

要求

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

另请参阅

CertGetCTLContextProperty

CertSetCertificateContextProperty

CryptEncodeObject

扩展属性函数