CertAddCertificateContextToStore 函数 (wincrypt.h)

  • 项目

CertAddCertificateContextToStore 函数将证书上下文添加到证书存储。

语法

BOOL CertAddCertificateContextToStore(
  [in]            HCERTSTORE     hCertStore,
  [in]            PCCERT_CONTEXT pCertContext,
  [in]            DWORD          dwAddDisposition,
  [out, optional] PCCERT_CONTEXT *ppStoreContext
);

参数

[in] hCertStore

证书存储的句柄。

[in] pCertContext

指向要添加到存储区 CERT_CONTEXT 结构的指针。

[in] dwAddDisposition

指定在存储中已存在匹配证书或指向匹配证书的链接时要执行的操作。 当前定义的处置值及其用法如下所示。

值 含义
CERT_STORE_ADD_ALWAYS
 函数不会对现有匹配证书或匹配证书的链接进行检查。 始终会向存储区添加新证书。 这可能会导致存储中出现重复项。
CERT_STORE_ADD_NEW
 如果存在匹配的证书或指向匹配证书的链接，则操作将失败。 GetLastError 返回CRYPT_E_EXISTS代码。
CERT_STORE_ADD_NEWER
 如果存在匹配的证书或指向匹配证书的链接，并且现有上下文的 NotBefore 时间等于或大于要添加的新上下文的 NotBefore 时间，则操作将失败， 并且 GetLastError 将返回CRYPT_E_EXISTS代码。

如果现有上下文的 NotBefore 时间小于要添加的新上下文的 NotBefore 时间，则会删除现有证书或链接，并创建一个新证书并将其添加到存储区。 如果匹配的证书或指向匹配证书的链接不存在，则会添加新链接。

如果 证书吊销列表 (CRL) 或 证书信任列表 (CTL) 进行比较，则使用 ThisUpdate 时间。
CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES
 如果存在匹配的证书或指向匹配证书的链接，并且现有上下文的 NotBefore 时间等于或大于要添加的新上下文的 NotBefore 时间，则操作将失败， 并且 GetLastError 将返回CRYPT_E_EXISTS代码。

如果现有上下文的 NotBefore 时间小于要添加的新上下文的 NotBefore 时间，则会在创建和添加新上下文之前删除现有上下文。 新添加的上下文从现有证书继承属性。

如果要比较 CRL 或 CTL，则使用 ThisUpdate 时间。
CERT_STORE_ADD_REPLACE_EXISTING
 如果存在指向匹配证书的链接，则会删除现有证书或链接，并创建一个新证书并将其添加到存储区。 如果匹配的证书或指向匹配证书的链接不存在，则会添加新链接。
CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES
 如果存储中存在匹配的证书，则不会替换现有上下文。 现有上下文从新证书继承属性。
CERT_STORE_ADD_USE_EXISTING
 如果存在匹配证书或指向匹配证书的链接，则使用现有证书或链接，并添加新证书的属性。 函数不会失败，但它不会添加新上下文。 如果 pCertContext 不为 NULL，则现有上下文将重复。

如果匹配的证书或指向匹配证书的链接不存在，则会添加新证书。

[out, optional] ppStoreContext

指向要创建已添加到存储的证书副本的指针的指针。

ppStoreContext 参数可以为 NULL，表示调用应用程序不需要添加的证书的副本。 如果创建副本，则必须使用 CertFreeCertificateContext 将其释放。

返回值

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

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

返回代码 说明
CRYPT_E_EXISTS
 如果设置了CERT_STORE_ADD_NEW并且存储中已存在证书，或者设置了CERT_STORE_ADD_NEWER并且存储区中存在一个证书，且该证书的 NotBefore 日期大于或等于要添加的证书上的 NotBefore 日期，则返回此值。
E_INVALIDARG
 dwAddDisposition 参数中指定了无效的处置值。
 

来自被调用函数 CertAddEncodedCertificateToStore 和 CertSetCertificateContextProperty 的错误可以传播到此函数。

注解

使用 CertDuplicateCertificateContext 不会复制证书上下文。 相反， 函数会创建上下文的新副本，并将其添加到 存储中。

除了编码的证书， CertDuplicateCertificateContext 还会复制上下文的属性，CERT_KEY_PROV_HANDLE_PROP_ID和CERT_KEY_CONTEXT_PROP_ID属性除外。

若要从证书存储中删除证书上下文，请使用 CertDeleteCertificateFromStore 函数。

注意 证书上下文的顺序可能不会在存储中保留。 若要访问特定证书，必须循环访问存储中的证书。
 

要求

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

另请参阅

CertAddEncodedCertificateToStore

CertSetCertificateContextProperty

证书函数