Managing a Certificate Store State

Several functions provide services for managing a certificate store state.

To gain access to certificates, the certificate store in which they are stored must be opened through a call to CertOpenStore or CertOpenSystemStore.

Usually a certificate store is opened in cached memory. It can be a new store or its contents can be loaded from the local registry, the registry on a remote computer, a disk file, a PKCS #7 message, or some other source.

CryptoAPI certificate store functions also allow a store to maintain certificates outside cached memory in, for example, an external database of certificates such as the one provided by the Microsoft Certificate Server Database.

One of the parameters of the CertOpenStore function, lpszStoreProvider, determines the type of store opened and the provider used to open that store. For examples of opening certificate stores using various providers, see Example C Code for Opening Certificate Stores.

CertCloseStore closes a certificate store. When a certificate store is closed, each of the certificate contexts in that store has its reference count reduced by one. Memory is freed for certificates whose reference count goes to zero.

Setting CERT_CLOSE_STORE_FORCE_FLAG with CertCloseStore closes the certificate store and frees memory for all of its certificate contexts regardless of their reference count. In some cases, such as in multithreaded programs, this cannot be desirable. If CERT_CLOSE_STORE_CHECK_FLAG is set, the store is closed, but a warning value is returned by the function if memory is still allocated for certificates whose reference counts have not been reduced to zero. If a certificate's reference count is greater than zero, a duplicate of that certificate context has not been freed. Use CertFreeCertificateContext, CertFreeCRLContext, and CertFreeCTLContext to free any certificates left open.

Note

A certificate context is a structure of type CERT_CONTEXT that has, among other members, a pointer to the encoded certificate BLOB and a pointer to a CERT_INFO structure. The CERT_INFO structure contains the most significant certificate data. For more information about certificate, certificate revocation list (CRL), and certificate trust list (CTL) context structures, see Encoding and Decoding a Certificate Context.

Each certificate context also contains a reference count indicating the number of copies of the context's address that have been assigned. Each time a certificate context is duplicated in any way, its reference count is incremented by one. Each time a pointer to a certificate context is freed, the reference count in the certificate context is decremented by one. When the reference count on a certificate context reaches zero, the memory holding the context is de-allocated. Memory allocated for a certificate context is also de-allocated when that context is in a store and the store is closed using CERT_CLOSE_STORE_FORCE_FLAG. If the memory for a context is de-allocated and pointers to that context are still in use, those pointers are no longer valid.

 

CertDuplicateStore increases the reference count on the store.

CertSaveStore saves the contents of a store to a disk file or a memory location, and

CertControlStore manages a store while it is open. An application with an open store can be notified when the persisted state of that store has changed by some other process. This could happen if new certificates were copied to the local computer store from a domain control computer.

When changes are discovered, the cached store can re-synchronize its cached store to match the persisted state of the store. CertControlStore also supports a process that copies cached store changes to permanent storage when these changes in the cached store are not automatically saved.

Certificate store-like certificate contexts can have extended properties. CertSetStoreProperty adds extended properties to a certificate store. CertGetStoreProperty retrieves any properties set on a certificate store. Currently, the only predefined certificate store property is a store's localized name.