CertAddCertificateContextToStore

The CertAddCertificateContextToStore function adds a certificate context to the certificate store.

#include <wincrypt.h>
BOOL WINAPI CertAddCertificateContextToStore(
  HCERTSTORE hCertStore,            // in
  PCCERT_CONTEXT pCertContext,      // in
  DWORD dwAddDisposition,           // in
  PCCERT_CONTEXT *ppStoreContext    // out, optional
);

Parameters

hCertStore

Handle to the certificate store.

pCertContext

Pointer to the certificate context that is to be added.

dwAddDisposition

Value that specifies the action to take if a matching certificate or a link to a matching certificate already exists in the store. Currently defined disposition values and their uses are:

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

ppStoreContext

A pointer to a pointer to the copy to be made of the certificate that was added to the store.

ppStoreContext can be NULL, indicating that the caller does not want a copy of the added certificate. If a copy is made, it must be freed by using CertFreeCertificateContext.

Return Values

TRUE if the function succeeded. FALSE if the function failed.

GetLastError returns the reason for any failures using the following error codes:

CRYPT_E_EXISTS: Returned if CERT_STORE_ADD_NEW is set and the certificate already exists in the store or if CERT_STORE_ADD_NEWER is set and a certificate exists in the store with a NotBefore date greater than or equal to the NotBefore date on the certificate to be added.
E_INVALIDARG: An invalid add disposition was specified by the dwAddDisposition argument.

Errors from the called functions, CertAddEncodedCertificateToStore and CertSetCertificateContextProperty may be propagated to this function.

Remarks

The certificate context is not duplicated using CertDuplicateCertContext. Instead, the function creates a new copy of the context and adds it to the store.

In addition to the encoded certificate, the function also copies the context's properties, with the exception of the CERT_KEY_PROV_HANDLE_PROP_ID and CERT_KEY_CONTEXT_PROP_ID properties.

Example

// **********************************************************
//  Declare variables.
HCERTSTORE      hLinkStoreHandle;
HCERTSTORE      hOriginalStoreHandle;
PCCERT_CONTEXT  DesiredCert = NULL;
//************************************************************
// Open a memory store where a new certificate will be added.
// For details, see CertOpenStore.
hLinkStoreHandle = CertOpenStore(CERT_STORE_PROV_MEMORY,0,NULL,0,NULL);
//*************************************************************
// Open a system store where certificates can be found
// to add to the memory store. 
// For details, see CertOpenStore.
hOriginalStoreHandle = CertOpenStore(CERT_STORE_PROV_SYSTEM,0,NULL,
CERT_SYSTEM_STORE_CURRENT_USER,L"MY");
//***************************************************************
// Get the first certificate in the system store.
DesiredCert=CertEnumCertificatesInStore(hOriginalStoreHandle,DesiredCert);              
//***************************************************************
// Add a certificate to hLinkStoreHandle store.
if(CertAddCertificateContextToStore(
     hLinkStoreHandle,             // The store handle.
     DesiredCert,                  // A pointer to a Cert.
CERT_STORE_ADD_USE_EXISTING,  // If a matching cert exists, 
// use it.
     NULL                          // Do not make any extra copy of
                                   // the certificate.
     )) 
printf("A certificate has been added to the store. \n");
else
printf("A certificate was not added to the store. \n");

QuickInfo