CertAddCertificateLinkToStore

[This is preliminary documentation and subject to change.]

The CertAddCertificateLinkToStore function adds a link in a certificate store to a certificate context in a different store. Instead of creating and adding a duplicate of the certificate context, this function adds a link to the original certificate wherever it may be. Because the link provides access to the original certificate context, setting an extended property in the linked certificate context changes that property as seen in the certificate's original location and by any other links to that certificate.

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

Parameters

hCertStore

Handle to the certificate store where the link is to be added.

pCertContext

Pointer to the certificate context that is to be linked.

dwAddDisposition

Value that specifies the action 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, the existing certificate is used. The function does not fail, but no new link is added. If no matching certificate or link to a matching certificate exists, a new link is added.
CERT_STORE_ADD_REPLACE_EXISTING: If a link to a matching certificate exists, that existing link is deleted and a new link is created and added to the store. If no matching certificate or link to a matching certificate exists, one is added.
CERT_STORE_ADD_ALWAYS: Makes no check for an existing matching certificate or link to a matching certificate. A new link is always added to the store. This may lead to duplicates in a store.
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 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, the function adds a new link to the store.

ppStoreContext

Pointer to a pointer to a copy of the link created. ppStoreContext can be NULL to indicate that a copy of the link is not needed. If a copy of the link is created, that copy must be freed using CertFreeCertificateContext.

Return Values

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

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

Error code	Description
CRYPT_E_EXISTS	For a dwAddDisposition of CERT_STORE_ADD_NEW, the certificate already exists in the store.
E_INVALIDARG	Invalid add disposition specified by the dwAddDisposition argument.

Remarks

Links cannot be added to a store opened as a collection. Stores opened as collections include all stores opened with CertOpenSystemStore or CertOpenStore using CERT_STORE_PROV_SYSTEM or CERT_STORE_PROV_COLLECTION. Also see CertAddStoreToCollection.

If links are used and CertCloseStore is called with CERT_CLOSE_STORE_FORCE_FLAG, the store using links must be closed before the store containing the original contexts is closed. If CERT_CLOSE_STORE_FORCE_FLAG is not used, the two stores may be closed in either order.

Example

HCERTSTORE      hLinkStoreHandle;
HCERTSTORE      hOriginalStoreHandle;
PCCERT_CONTEXT  DesiredCert = NULL;
// Open a memory store where links 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
// so that links can be added to hLinkStore. 
// 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 link to the certificate to hLinkStoreHandle store.
if(CertAddCertificateLinkToStore(
     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 link has been added to the store. \n");
else
printf("A new link to a cert was not added to the store. \n");

QuickInfo