CertSetCertificateContextProperty 函数 (wincrypt.h)

项目
08/27/2023

CertSetCertificateContextProperty 函数为指定的证书上下文设置扩展属性。

语法

BOOL CertSetCertificateContextProperty(
  [in] PCCERT_CONTEXT pCertContext,
  [in] DWORD          dwPropId,
  [in] DWORD          dwFlags,
  [in] const void     *pvData
);

参数

[in] pCertContext

指向 CERT_CONTEXT 结构的指针。

[in] dwPropId

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

注意CRYPT_INTEGER_BLOB 主题中介绍了 CRYPT_HASH_BLOB和CRYPT_DATA_BLOB。

CERT_ACCESS_STATE_PROP_ID

pvData 的数据类型：指向 DWORD 值的指针。

返回一个 DWORD 值，该值指示是否持久执行对证书的写入操作。如果证书位于内存存储中或以只读身份打开的基于注册表的存储中，则不会设置 DWORD 值。

CERT_AIA_URL_RETRIEVED_PROP_ID

此标识符是保留的。

CERT_ARCHIVED_KEY_HASH_PROP_ID

pvData 的数据类型：指向CRYPT_HASH_BLOB结构的指针。

此属性保存证书上下文的加密密钥哈希。

CERT_ARCHIVED_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

指示在枚举期间跳过证书。仍可以通过显式搜索操作（例如查找具有特定哈希或特定序列号的证书）找到具有此属性集的证书。此属性可以设置为空 BLOB{0,NULL} 。

CERT_AUTHORITY_INFO_ACCESS_PROP_ID

此标识符是保留的。

CERT_AUTO_ENROLL_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

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

CERT_AUTO_ENROLL_RETRY_PROP_ID

此标识符是保留的。

CERT_BACKED_UP_PROP_ID

此标识符是保留的。

CERT_CA_DISABLE_CRL_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

禁用证书吊销列表 (CRL) 检索证书颁发机构 (CA) 使用的证书。如果 CA 证书包含此属性，则它还必须包含 CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID 属性。

CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

包含联机证书状态协议列表， (OCSP) URL 用于 CA 证书颁发的证书。数组内容是抽象语法表示法 One (ASN.1) X509_AUTHORITY_INFO_ACCESS 结构的 编码字节， 其中 pszAccessMethod 设置为 szOID_PKIX_OCSP。

CERT_CROSS_CERT_DIST_POINTS_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

设置交叉证书的位置。此值仅适用于证书，不适用于证书吊销列表 (CRL) 或证书信任列表 (CTL) 。 CRYPT_DATA_BLOB 结构包含抽象语法表示法 One (ASN.1) 编码CROSS_CERT_DIST_POINTS_INFO结构，该结构使用具有 lpszStuctType 参数X509_CROSS_CERT_DIST_POINTS值的 CryptEncodeObject 函数进行编码。

CERT_CTL_USAGE_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

CRYPT_DATA_BLOB 结构包含 ASN.1 编码CTL_USAGE结构。此结构使用 CryptEncodeObject 函数进行编码，并设置了X509_ENHANCED_KEY_USAGE值。

CERT_DATE_STAMP_PROP_ID

pvData 的数据类型：指向 FILETIME 结构的指针。

此属性设置证书添加到存储的时间。

CERT_DESCRIPTION_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

由证书 UI 设置和显示的属性。此属性允许用户描述证书的用法。

CERT_EFS_PROP_ID

此标识符是保留的。

CERT_ENHKEY_USAGE_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

一个属性，指示 pvData 参数指向包含 ASN.1 编码 CERT_ENHKEY_USAGE 结构的 CRYPT_DATA_BLOB 结构。此结构使用 CryptEncodeObject 函数进行编码，并设置了X509_ENHANCED_KEY_USAGE值。

CERT_ENROLLMENT_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

包含 RequestID、CADNSName、CAName 和 DisplayName 的挂起请求的注册信息。数据格式的定义如下。

字节	目录
前 4 个字节	挂起的请求 ID
接下来 4 个字节	CADNSName 大小，以字符为单位，包括终止 null 字符，后跟具有终止 null 字符的 CADNSName 字符串
接下来 4 个字节	CAName 大小，以字符为单位，包括终止 null 字符，后跟具有终止 null 字符的 CAName 字符串
接下来 4 个字节	DisplayName 大小，以字符为单位，包括终止 null 字符，后跟具有终止 null 字符的 DisplayName 字符串

CERT_EXTENDED_ERROR_INFO_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性设置一个字符串，其中包含证书上下文的扩展错误信息。

CERT_FORTEZZA_DATA_PROP_ID

此标识符是保留的。

CERT_FRIENDLY_NAME_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

CRYPT_DATA_BLOB结构包含证书的显示名称。

CERT_HASH_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性通过调用 CertGetCertificateContextProperty 函数隐式设置。

CERT_HCRYPTPROV_OR_NCRYPT_KEY_HANDLE_PROP_ID

pvData 的数据类型：指向HCRYPTPROV_OR_NCRYPT_KEY_HANDLE数据类型的指针。

此属性调用 NCryptIsKeyHandle 以确定此是否为 NCRYPT_KEY_HANDLE。对于 NCRYPT_KEY_HANDLE，设置 CERT_NCRYPT_KEY_HANDLE_PROP_ID;否则，它将设置 CERT_KEY_PROV_HANDLE_PROP_ID。

CERT_HCRYPTPROV_TRANSFER_PROP_ID

设置与证书关联的 CAPI 密钥的句柄。

CERT_IE30_RESERVED_PROP_ID

此标识符是保留的。

CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性设置与用于对此证书进行签名的私钥关联的公钥的 MD5 哈希。

CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

CRYPT_DATA_BLOB 结构包含此证书中颁发者名称和序列号的 MD5 哈希。

CERT_KEY_CONTEXT_PROP_ID

pvData 的数据类型：指向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 成员存在，则更新该成员。如果不存在，则会使用 dwKeySpec 创建它，并由CERT_KEY_PROV_INFO_PROP_ID进行初始化。如果未设置CERT_STORE_NO_CRYPT_RELEASE_FLAG，则当属性设置为 NULL 或最终释放 CERT_CONTEXT 结构时，将隐式释放 hCryptProv 值。

CERT_KEY_PROV_INFO_PROP_ID

pvData 的数据类型：指向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_NCRYPT_KEY_HANDLE_PROP_ID

pvData 的数据类型：指向NCRYPT_KEY_HANDLE数据类型的指针。

此属性设置证书私钥 的NCRYPT_KEY_HANDLE ，并将 dwKeySpec 设置为 CERT_NCRYPT_KEY_SPEC。

CERT_NCRYPT_KEY_HANDLE_TRANSFER_PROP_ID

设置与证书关联的 CNG 密钥的句柄。

CERT_NEW_KEY_PROP_ID

此标识符是保留的。

CERT_NEXT_UPDATE_LOCATION_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

CRYPT_DATA_BLOB 结构包含 ASN.1 编码的CERT_ALT_NAME_INFO结构，该结构使用设置了 X509_ALTERNATE_NAME 值的 CryptEncodeObject 函数进行编码。

CERT_NEXT_UPDATE_LOCATION_PROP_ID目前仅用于 CTL。

CERT_NO_AUTO_EXPIRE_CHECK_PROP_ID

此标识符是保留的。

CERT_OCSP_CACHE_PREFIX_PROP_ID

此标识符是保留的。

CERT_OCSP_RESPONSE_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性设置编码的联机证书状态协议 (OCSP) 此证书的CERT_SERVER_OCSP_RESPONSE_CONTEXT 响应。

CERT_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性是通过调用 CertGetCertificateContextProperty 函数隐式设置的。

Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支持此标识符。

CERT_PUBKEY_ALG_PARA_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性与支持算法参数继承的公钥一起使用。数据 BLOB 包含 ASN.1 编码的 PublicKey 算法参数。对于 DSS，这些参数是使用 CryptEncodeObject 函数编码的参数。仅当定义了CMS_PKCS7时，才使用此方法。

CERT_PUBKEY_HASH_RESERVED_PROP_ID

此标识符是保留的。

CERT_PVK_FILE_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

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

CERT_RENEWAL_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性指定续订证书的哈希。

CERT_REQUEST_ORIGINATOR_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

CRYPT_DATA_BLOB 结构包含一个以 null 结尾的 Unicode 字符串，该字符串包含证书上下文请求发起的 DNS 计算机名称。

CERT_ROOT_PROGRAM_CERT_POLICIES_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

返回指向已编码 CERT_POLICIES_INFO 结构的指针，该结构包含上下文的根证书的应用程序策略。可以使用 CryptDecodeObject 函数对此属性进行解码，其中 lpszStructType 参数设置为 X509_CERT_POLICIES ， 将 dwCertEncodingType 参数设置为 X509_ASN_ENCODING 位 ORPKCS_7_ASN_ENCODING的组合。

CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID

此标识符是保留的。

CERT_SIGN_HASH_CNG_ALG_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性是通过调用 CertGetCertificateContextProperty 函数隐式设置的。

Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支持此标识符。

CERT_SHA1_HASH_PROP_ID

pvData 的数据类型：指向CRYPT_HASH_BLOB结构的指针。

此属性是通过调用 CertGetCertificateContextProperty 函数隐式设置的。

CERT_SIGNATURE_HASH_PROP_ID

pvData 的数据类型：指向CRYPT_HASH_BLOB结构的指针。

如果签名哈希不存在，则使用 CryptHashToBeSigned 函数计算该哈希。 pvData 指向现有哈希或计算哈希。通常，SHA 的哈希长度为 20 字节，MD5 的长度为 16 字节。

CERT_SMART_CARD_DATA_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性设置智能卡证书上下文的智能卡数据属性。

CERT_SMART_CARD_ROOT_INFO_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性设置智能卡根证书上下文的信息属性。

CERT_SOURCE_LOCATION_PROP_ID

此标识符是保留的。

CERT_SOURCE_URL_PROP_ID

此标识符是保留的。

CERT_SUBJECT_DISABLE_CRL_PROP_ID

此标识符是保留的。

CERT_SUBJECT_INFO_ACCESS_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性将证书上下文的使用者信息访问扩展设置为编码 CERT_SUBJECT_INFO_ACCESS 结构。

CERT_SUBJECT_NAME_MD5_HASH_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

返回证书上下文的编码使用者名称的 MD5 哈希。

CERT_SUBJECT_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID

此标识符是保留的。

CERT_SUBJECT_PUB_KEY_BIT_LENGTH_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性是通过调用 CertGetCertificateContextProperty 函数隐式设置的。

Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支持此标识符。

CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID

pvData 的数据类型：指向CRYPT_DATA_BLOB结构的指针。

此属性设置此证书公钥的 MD5 哈希。

pvData 是指向 CRYPT_DATA_BLOB 结构的指针。

用户可以使用从 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	属性无效。指定的标识符大于 0x0000FFFF，或者对于 CERT_KEY_CONTEXT_PROP_ID 属性，在 CERT_KEY_CONTEXT 结构中指定了无效的 cbSize 成员。

注解

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

代码可以使用宏来评估证书上下文的哈希类。 Wincrypt.h 标头为此定义以下宏。这些宏由 CertSetCertificateContextProperty 函数在内部使用。

IS_CERT_HASH_PROP_ID (X) IS_PUBKEY_HASH_PROP_ID (X) IS_CHAIN_HASH_PROP_ID (X) 每个宏采用 dwPropId (X) 值作为输入，计算结果为布尔值。下表显示了每个宏的计算结果为 TRUE 的 dwPropId 值。

宏	如果 dwPropId 为，则计算结果为 TRUE
IS_CERT_HASH_PROP_ID (dwPropId)	CERT_SHA1_HASH_PROP_ID， CERT_MD5_HASH_PROP_ID，或 CERT_SIGNATURE_HASH_PROP_ID
IS_PUBKEY_HASH_PROP_ID (dwPropId)	CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID 或 CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID
IS_CHAIN_HASH_PROP_ID (dwPropId)	CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID， CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID， CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID，或 CERT_SUBJECT_NAME_MD5_HASH_PROP_ID

如果在 dwPropId 参数中设置了CERT_SIGN_HASH_CNG_ALG_PROP_ID、CERT_SUBJECT_PUB_KEY_BIT_LENGTH_PROP_ID或CERT_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID属性，则IS_STRONG_SIGN_PROP_ID (x ) 宏的计算结果为 TRUE。

示例

有关使用此函数的示例，请参阅示例 C 程序：获取和设置证书属性。

要求

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