Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function adds a certificate context to the certificate store.

Syntax 

BOOL WINAPI CertAddCertificateContextToStore(
  HCERTSTORE 
hCertStore,
  PCCERT_CONTEXT 
pCertContext,
  DWORD 
dwAddDisposition,
  PCCERT_CONTEXT* 
ppStoreContext
);

Parameters

hCertStore

[in] Handle to a certificate store.

pCertContext

[in] Pointer to the CERT_CONTEXTstructure to be added to the store.

dwAddDisposition

[in] Specifies the action to take if a matching certificate or a link to a matching certificate already exists in the store. The following table shows the currently defined disposition values and their uses.

Value Description

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. The GetLastErrorfunction returns the CRYPT_E_EXISTS code.

CERT_STORE_ADD_NEWER

If a matching certificate or a link to a matching certificate exists, the function compares the NotBeforetimes on the certificates. If the existing certificate has a NotBeforetime less than the NotBeforetime 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 NotBeforetime greater than or equal to the NotBeforetime on the certificate to be added, the function fails with the GetLastErrorfunction returning the CRYPT_E_EXISTS code.

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.

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

[out] Optional. Pointer to a pointer to the copy to be made of the certificate that was added to the store.

This parameter can be NULL, indicating that the calling application does not require a copy of the added certificate. If a copy is made, it must be freed by using the CertFreeCertificateContextfunction.

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 the GetLastErrorfunction. The following table shows some possible error codes.

Value Description

CRYPT_E_EXISTS

This value is 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 NotBeforedate greater than or equal to the NotBeforedate on the certificate to be added.

E_INVALIDARG

An invalid disposition value was specified in the dwAddDispositionparameter.

Errors from the called functions, CertAddEncodedCertificateToStoreand CertSetCertificateContextProperty, can be propagated to this function.

Remarks

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

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

Requirements

Header wincrypt.h
Library crypt32.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also