Expand Minimize

CertAddCertificateLinkToStore function

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.

Syntax


BOOL WINAPI CertAddCertificateLinkToStore(
  _In_       HCERTSTORE hCertStore,
  _In_       PCCERT_CONTEXT pCertContext,
  _In_       DWORD dwAddDisposition,
  _Out_opt_  PCCERT_CONTEXT *ppStoreContext
);

Parameters

hCertStore [in]

A handle to the certificate store where the link is to be added.

pCertContext [in]

A pointer to the CERT_CONTEXT structure to be linked.

dwAddDisposition [in]

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 as follows.

ValueMeaning
CERT_STORE_ADD_ALWAYS

The function makes no check for an existing matching certificate or link to a matching certificate. A new certificate is always added to the store. This can lead to duplicates in a store.

CERT_STORE_ADD_NEW

If a matching certificate or a link to a matching certificate exists, the operation fails. GetLastError returns the CRYPT_E_EXISTS code.

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_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.

 

ppStoreContext [out, optional]

A pointer to a pointer to a copy of the link created. The ppStoreContext parameter 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 the CertFreeCertificateContext function.

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. For extended error information, call GetLastError. Some possible error codes follow.

Return codeDescription
CRYPT_E_EXISTS

For a dwAddDisposition parameter of CERT_STORE_ADD_NEW, the certificate already exists in the store.

E_INVALIDARG

A disposition value that is not valid was specified in the dwAddDisposition parameter.

 

Remarks

Because the link provides access to the original certificate context, setting an extended property in the linked certificate context changes that extended property in the certificate's original location and in any other links to that certificate.

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. For more information, see CertAddStoreToCollection.

If links are used and CertCloseStore is called with CERT_CLOSE_STORE_FORCE_FLAG, the store that uses links must be closed before the store that contains the original contexts is closed. If CERT_CLOSE_STORE_FORCE_FLAG is not used, the two stores can be closed in either order.

To remove the certificate context link from the certificate store, use the CertDeleteCertificateFromStore function.

Examples

For an example that uses this function, see Example C Program: Certificate Store Operations. For additional code that uses this function, see Example C Program: Collection and Sibling Certificate Store Operations.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Crypt32.lib

DLL

Crypt32.dll

See also

Certificate Functions
CertAddCRLLinkToStore
CertAddCTLLinkToStore
CertAddStoreToCollection
CertCloseStore
CertFreeCertificateContext
CertOpenStore
CertOpenSystemStore

 

 

Community Additions

ADD
Show:
© 2014 Microsoft