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。 接下來有一些可能的錯誤碼。

傳回碼 Description
CRYPT_E_EXISTS
 如果已設定CERT_STORE_ADD_NEW且憑證已存在於存放區中，或已設定CERT_STORE_ADD_NEWER，且存放區中有大於或等於所要新增憑證之 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
程式庫 Crypt32.lib
Dll Crypt32.dll

另請參閱

CertAddEncodedCertificateToStore

CertSetCertificateContextProperty

憑證函數