CertAddCTLContextToStore function (wincrypt.h)

Article
10/13/2021

The CertAddCTLContextToStore function adds a certificate trust list (CTL) context to a certificate store.

Syntax

BOOL CertAddCTLContextToStore(
  [in]            HCERTSTORE    hCertStore,
  [in]            PCCTL_CONTEXT pCtlContext,
  [in]            DWORD         dwAddDisposition,
  [out, optional] PCCTL_CONTEXT *ppStoreContext
);

Parameters

[in] hCertStore

Handle of a certificate store.

[in] pCtlContext

A pointer to the CTL_CONTEXT structure to be added to the store.

[in] dwAddDisposition

Specifies the action to take if a matching CTL or a link to a matching CTL already exists in the store. Currently defined disposition values and their uses are as follows.

Value	Meaning
CERT_STORE_ADD_ALWAYS	Makes no check for an existing matching CTL or link to a matching CTL. A new CTL is always added to the store. This can lead to duplicates in a store.
CERT_STORE_ADD_NEW	If a matching CTL or a link to a matching CTL exists, the operation fails. GetLastError returns the CRYPT_E_EXISTS code.
CERT_STORE_ADD_NEWER	If a matching CTL or a link to a matching CTL exists, the ThisUpdate times on the CTLs are compared. If the existing CTL has a ThisUpdate time less than the ThisUpdate time on the new CTL, the old CTL or link is replaced just as with CERT_STORE_ADD_REPLACE_EXISTING. If the existing CTL has a ThisUpdate time greater than or equal to the ThisUpdate time on the CTL to be added, the function fails with GetLastError returning the CRYPT_E_EXISTS code. If a matching CTL or a link to a matching CTL is not found in the store, a new CTL is added to the store.
CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES	The action is the same as for CERT_STORE_ADD_NEWER, except that if an older CTL is replaced, the properties of the older CTL are incorporated into the replacement CTL.
CERT_STORE_ADD_REPLACE_EXISTING	If a matching CTL or a link to a matching CTL exists, the existing CTL or link is deleted and a new CTL is created and added to the store. If a matching CTL or a link to a matching CTL does not exist, one is added.
CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES	If a matching CTL exists in the store, that existing context is deleted before creating and adding the new context. The added context inherits properties from the existing CTL.
CERT_STORE_ADD_USE_EXISTING	If a matching CTL or a link to a matching CTL exists, that existing CTL is used and properties from the new CTL are added. The function does not fail, but no new CTL is added. If ppCertContext is not NULL, the existing context is duplicated. If a matching CTL or a link to a matching CTL does not exist, a new CTL is added.

[out, optional] ppStoreContext

Pointer to a pointer to the decoded CTL context. This optional parameter can be NULL indicating that the calling application does not require a copy of the added or existing CTL. If a copy is made, that context must be freed using CertFreeCTLContext.

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. Errors from the called functions CertAddEncodedCRLToStore and CertSetCRLContextProperty can be propagated to this function.

For extended error information, call GetLastError. Some possible error codes follow.

Return code	Description
CRYPT_E_EXISTS	This error is returned if CERT_STORE_ADD_NEW is set and the CTL exists in the store or if CERT_STORE_ADD_NEWER is set and a CTL exists in the store with a ThisUpdate date greater than or equal to the ThisUpdate date on the CTL to be added.
E_INVALIDARG	An add disposition that is not valid was specified by the dwAddDisposition parameter.

Remarks

The CTL context is not duplicated using CertDuplicateCTLContext. Instead, a new copy is created and added to the store. In addition to the encoded CTL, the context's properties are copied.

To remove the CTL context from the certificate store, use the CertDeleteCTLFromStore function.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2003 [desktop apps \| UWP apps]
Target Platform	Windows
Header	wincrypt.h
Library	Crypt32.lib
DLL	Crypt32.dll