CertOpenStore

[This is preliminary documentation and subject to change.]

The CertOpenStore function opens a certificate store using a specified store provider type. This function provides simple ways to open a certificate store for ordinary purposes and more complex options for special cases.

#include <wincrypt.h>
HCERTSTORE WINAPI CertOpenStore(
  LPCSTRlpszStoreProvider,                // in
  DWORD dwMsgAndCertEncodingType,         // in
  HCRYPTPROV hCryptProv,                  // in
  DWORD dwFlags,                          // in
  const void *pvPara                      // in
);

Parameters

lpszStoreProvider

Specifies the store provider type. The following predefined store provider types furnish most common application needs.

CERT_STORE_PROV_MEMORY

CERT_STORE_PROV_FILE

CERT_STORE_PROV_FILENAME

CERT_STORE_PROV_COLLECTION

CERT_STORE_PROV_REG

CERT_STORE_PROV_SYSTEM

CERT_STORE_PROV_SYSTEM_REGISTRY

CERT_STORE_PROV_PHYSICAL

CERT_STORE_PROV_MSG

CERT_STORE_PROV_PKCS7

CERT_STORE_PROV_SERIALIZED

CERT_STORE_PROV_LDAP

Most of the provider names passed to lpszStoreProvider may be prefixed with 'sz_' as in sz_CERT_STORE_PROV_FILE. Calling a provider with a name prefixed by 'sz_' does not change that provider in any way.

Provider types that pass a string to pvPara have alternate forms: one that passes the string as unicode ( an LPCWSTR variable) and another that passes the string as ASCII ( an LPCSTR variable). The names of providers that pass ASCII strings must be suffixed with '_A' as in CERT_STORE_PROV_FILENAME_A. Providers that pass unicode strings may be suffixed with '_W' as in sz_CERT_STORE_PROV_REG_W. Provider names without either the '_A' or '_W' use the default, unicode form.

The store provider type passed in lpszStoreProvider determines the type of the parameter passed in pvPara and the use and meaning of the HIWORD of dwFlags.

The predefined store provider types are defined as follows:

CERT_STORE_PROV_MEMORY

Creates a certificate store in cached memory but no certificates, CRLs, or CTLs are initially loaded into the store This provider type is typically used to create a temporary store.

pvPara is not used.

Any addition of certificates, CRLs, or CTLs or changes in properties of certificates, CRLs, or CTLs in a memory store are not automatically saved. They may be saved to a file or to a memory blob using CertSaveStore.

CERT_STORE_PROV_FILE.

Initializes the store with certificates, CRLs, and CTLs read from a specified open file.

This provider expects the file to contain only a serialized store and not either PKCS #7 signed messages or a single encoded certificate.

The handle of a file opened using CreateFile is passed in pvPara. The file pointer should be positioned at the beginning of the serialized store information. After the data in the serialized store has been loaded into the certificate store, the file pointer is positioned at the beginning of any data that may follow the serialized store data in the file.

If dwFlags CERT_FILE_STORE_COMMIT_ENABLE is set, the file handle is duplicated and the store is always committed as a serialized store.

The file is not closed when the store is closed.

CERT_STORE_PROV_FILENAME

Initializes the store with certificates, CRLs, and CTLs from a file. The provider opens the file and first attempts to read the file as a serialized store, then as a PKCS #7 signed message, and, finally, as a single encoded certificate.

dwMsgAndCertEncodingType must contain the encoding types to be used with both messages and certificates.

For the FILENAME providers: if the file contains an X509 encoded certificate, the open fails with ERROR_ACCESS_DENIED.

If dwFlags CERT_STORE_CREATE_NEW_FLAG and CERT_FILE_STORE_COMMIT_ENABLE are set, CreateFile uses CREATE_NEW. If CERT_STORE_OPEN_EXISTING is set, it uses OPEN_EXISTING. Otherwise, it defaults to OPEN_ALWAYS.

If CERT_FILE_STORE_COMMIT_ENABLE is set, the file is committed as either a PKCS #7 or a serialized store depending on the type read when the file opened. However, if the file was empty, if the filename has either a ".p7c" or ".spc" extension it is committed as a PKCS #7. Otherwise, its committed as a serialized store.

The name of an existing, unopened file is passed in pvPara as a unicode or ASCII string.

CERT_STORE_PROV_COLLECTION

Opens a store that will be a collection of other stores. Stores are added to or removed from the collection using CertAddStoreToCollection and CertRemoveStoreFromCollection. When a store is added to a collection, all certificates, CRLs, and CTLs in that store become available to finds or enumerations of the collection store.

pvPara should be set to NULL and the HIWORD of dwFlags set to 0.

CERT_STORE_PROV_REG.

Initializes the store with certificates, CRLs, and CTLs from a registry. subkey. The handle of an open registry hKey is passed in pvPara.

This provider opens or creates "Certificates," "CRLs," and "CTLs" registry subkeys under the hKey passed in pvPara. The input hKey is not closed by the provider. Before returning, the provider opens its own copy of the hKey passed in pvPara.

When CERT_STORE_READONLY_FLAG is set in the LOWORD of dwFlags, registry subkeys are opened via RegOpenKey with KEY_READ_ACCESS. Otherwise, registry subkeys are created via RegCreateKey with KEY_ALL_ACCESS.

Any changes to the contents of the opened store are immediately persisted to the registry. However, if CERT_STORE_READONLY_FLAG is set in the LOWORD of dwFlags , any attempt to add to the contents of the store or to change a context's property results in an error with GetLastError returning E_ACCESSDENIED.

CERT_STORE_PROV_SYSTEM

Initializes the store with certificates, CRLs, and CTLs from the specified system store. The system store is a logical, collection store consisting of one or more physical stores. A physical store associated with a system store is registered with the CertRegisterPhysicalStore function. After the system store is opened, all of the physical stores that are associated with it are also opened by calls to CertOpenStore and are added to the system store collection using CertAddStoreToCollection.

The HIWORD of dwFlags indicates the system store location, normally set to CERT_SYSTEM_STORE_CURRENT_USER. See the section on dwFlags and System Store Locations for details about registry locations.

Some system store locations can be open remotely. See System Store Locations for details.

A system store name, passed as a unicode or ASCII string, such as "MY," or "Root," is passed in pvPara.

CERT_STORE_PROV_SYSTEM_REGISTRY

Initializes the store with certificates, CRLs, and CTLs from a physical registry store. The physical store is not opened as a collection store. Enumerations and finds go through only the certificates, CRLs, and CTLs in that one physical store. The implementation of this provider is the same as the CERT_STORE_PROV_SYSTEM provider implemented in NT 4.0.

The HIWORD of dwFlags indicates the system store location, normally set to CERT_SYSTEM_STORE_CURRENT_USER. See the section on dwFlags.

Some system store locations can be open remotely. See System Store Locations for details.

A system store name, passed as a unicode or ASCII string, such as "MY," or "Root," is passed in pvPara.

CERT_STORE_PROV_PHYSICAL

Initializes the store with certificates, CRLs and CTLs from a specified physical store that is a member of a logical system store.

The HIWORD of dwFlags indicates the system store location, normally CERT_SYSTEM_STORE_CURRENT_USER. See the section on dwFlags for details.

Some physical store locations can be open remotely. Both the system store name and physical names are passed in pvPara. The two names are separated with an intervening "\", as, for example, "Root\.LocalMachine." Here, Root is the name of the system store and .LocalMachine is the name of the physical store. The system and physical store names are unicode strings and can not contain any backslashes.

CERT_STORE_PROV_MSG.

Initializes the store with certificates, CRLs, and CTLs from the specified cryptographic message. dwMsgAndCertEncodingType must contain the encoding types used with both messages and certificates. The HCRYPTMSG handle of the encoded message, returned by a call to CryptMsgOpenToDecode, is passed in pvPara

CERT_STORE_PROV_PKCS7

Initializes the store with certificates, CRLs, and CTLs from an encoded PKCS #7 signed message. dwMsgAndCertEncodingType must specify the encoding types to be used with both messages and certificates. A pointer to the encoded message's blob, a CRYPT_DATA_BLOB, is passed in pvPara

CERT_STORE_PROV_SERIALIZED

Initializes the store with certificates, CRLs, and CTLs from a memory location containing a serialized store.

A pointer to a CRYPT_DATA_BLOB serialized memory blob is passed in pvPara.

CERT_STORE_PROV_LDAP

Initializes the store with certificates, CRLs, and CTLs from the results of the query specified by a LDAP URL. The query as a unicode string is passed in pvPara. In order to do writes to the store, the URL must specify a BASE query with no filter and a single attribute.

Additional store providers may be installed or registered via CryptInstallOIDFunctionAddress or CryptRegisterOIDFunction. For additional information, see Extending CertOpenStore Functionality.

dwMsgAndCertEncodingType

This parameter is applicable only to the CERT_STORE_PROV_MSG, CERT_STORE_PROV_PKCS7, or CERT_STORE_PROV_FILENAME provider types. For all other provider types, this parameter is unused and should be set to 0. The LOWORD specifies the encoding type of certificates, CRLs, and CTLs in the cryptographic message. The HIWORD specifies the encoding type of the message.

Both a certificate and a message encoding type are required. They are specified by combining the two encoding types with a bitwise OR operation. The most common encoding types are used by passing X509_ASN_ENCODING | PKCS_7_ASN_ENCODING as this parameter.

hCryptProv

Specifies a handle to a cryptographic provider. Passing NULL in this parameter causes an appropriate, default provider to be used. Using the default provider is recommend. The default or specified cryptographic provider verifies the signature of a subject certificate, CRL, or CTL and to compute the hash when CertGetCertificateContextProperty , CertGetCTLContextProperty, or CertGetCRLContextProperty is called with hash PROP_IDs

dwFlags

dwFlags consist of HIWORD and LOWORD values that are combined using a bitwise OR.

The LOWORD portion of dwFlags control a variety of general characteristics of the certificate store opened. It can be used with all store provider types. Currently defined LOWORD portions values are:

CERT_STORE_NO_CRYPT_RELEASE_FLAG

CERT_STORE_READONLY_FLAG

CERT_STORE_DELETE_FLAG

CERT_STORE_OPEN_EXISTING_FLAG

CERT_STORE_CREATE_NEW_FLAG

CERT_STORE_SET_LOCALIZED_NAME_FLAG

CERT_STORE_DEFER_CLOSE_UNTIL_LAST_FREE_FLAG

CERT_STORE_NO_CRYPT_RELEASE_FLAG

This flag is valid only when a non-default cryptographic provider is used. When this flag is set, a non-default hCryptProv is not automatically released when the certificate store is closed.

CERT_STORE_READONLY_FLAG

When this flag is set, any attempt to change the contents of the store results in an error. When this flag is set and a registry based store provider is being used, the registry subkeys are opened via RegOpenKey with KEY_READ_ACCESS. Otherwise, the registry subkeys are created via RegCreateKey with KEY_ALL_ACCESS.

CERT_STORE_DELETE_FLAG.

When this flag is set, the store is deleted instead of being opened. CertOpenStore returns NULL for both success and failure of the deletion. To determine the success of the delete, call GetLastError which returns 0 if the store was deleted and nonzero if it was not deleted.

CERT_STORE_OPEN_EXISTING_FLAG.

When set, only an existing store can be opened. If the store did not exist, the function fails.

CERT_STORE_CREATE_NEW_FLAG.

When set, a new store is created if one did not exist. The function fails if the store already exists.

If neither CERT_STORE_OPEN_EXISTING_FLAG nor CERT_STORE_CREATE_NEW_FLAG is set, a store is opened if it exists, or is created and opened if it did not already exist.

CERT_STORE_SET_LOCALIZED_NAME_FLAG

If supported, the provider sets the store's CERT_STORE_LOCALIZED_NAME_PROP_ID property. This name can be retrieved by calling CertGetStoreProperty with dwPropID set to CERT_STORE_LOCALIZED_NAME_PROP_ID. This flag is supported for providers CERT_STORE_PROV_FILENAME, CERT_STORE_PROV_SYSTEM, CERT_STORE_PROV_SYSTEM_REGISTRY, and CERT_STORE_PROV_PHYSICAL_W.

CERT_STORE_DEFER_CLOSE_UNTIL_LAST_FREE_FLAG

When this flag is set, the closing of a store's provider may not be done when CertCloseStore is called but will deferred if certificates, CRLs, or CTLs obtained from the store are still in use. The store will actually be closed when the last certificate, CRL, or CTL obtained from the store is freed. Any changes made to properties of these certificates, CRLs, and CTLs, even after the call to CertCloseStore, will be persisted.

If this flag is not set and certificates, CRLs, or CTL obtained from the store are still in use, the properties of those certificates, CRLs and CTLs may be changed, but those changes will not be persisted. By setting this flag, those changes will be persisted.

Note that setting this flag causes extra overhead in doing context duplications and frees.

If CertCloseStore is called with CERT_CLOSE_STORE_FORCE_FLAG, CERT_STORE_DEFER_CLOSE_UNTIL_LAST_FREE_FLAG is ignored,

When this flag is set and a non-NULL HCRYPTPROV is passed, that provider will continue to be used even after the call to CertCloseStore.

dwFlags HIWORD values are combined using a bitwise OR with LOWORD flag values

The HIWORD of dwFlags is used to specify system store registry locations for system store provider types, CERT_STORE_PROV_SYSTEM, CERT_STORE_PROV_SYSTEM_REGISTER, and CERT_STORE_PROV_PHYSICAL. The following are defined HIWORD values associated with system store providers:

CERT_SYSTEM_STORE_CURRENT_USER
CERT_SYSTEM_STORE_LOCAL_MACHINE
CERT_SYSTEM_STORE_CURRENT_SERVICE
CERT_SYSTEM_STORE_SERVICES
CERT_SYSTEM_STORE_USERS
CERT_SYSTEM_STORE_CURRENT_USER_GROUP_POLICY
CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY

Each system store location opens, by default, relative to the HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE or HKEY_USERS predefined registry key. See System Store Locations for additional details.

Two additional system store flags can set in the HIWORD of dwFlags:

CERT_SYSTEM_STORE_RELOCATE_FLAG
CERT_SYSTEM_STORE_UNPROTECTED_FLAG

CERT_SYSTEM_STORE_RELOCATE_FLAG: This flag can be set to override the default location of a system store. When it is set, pvPara must pass a pointer to a CERT_SYSTEM_STORE_RELOCATE_PARA structure rather than a string. The data structure indicates both the name of the store and its location in the registry.
CERT_SYSTEM_STORE_UNPROTECTED_FLAG: By default, when the CurrentUser "Root" store is opened, any SystemRegistry roots not on the protected root list are deleted from the cache before CertOpenStore returns. When this flag is set, this default is overridden and all of the roots in the SystemRegistry are returned and no check of the protected root list is made.

Two addition HIWORD flags have been added for the CERT_STORE_PROV_REGISTRY provider.

CERT_REGISTRY_STORE_SERIALIZED_FLAG
CERT_REGISTRY_STORE_REMOTE_FLAG

CERT_REGISTRY_STORE_SERIALIZED_FLAG

When this flag is set, the CERT_STORE_PROV_REG provider saves certificates, CRLs, and CTLs into a single, serialized store subkey instead of the default which is that each certificate, CRL, or CTL is saved as a separate registry subkey under the appropriate subkey.

This flag is mainly used for stores downloaded from the GPT such as the CurrentUserGroupPolicy and LocalMachineGroupPolicy stores.

When CERT_REGISTRY_STORE_SERIALIZED_FLAG is set, store adds, deletes, or property changes are not persisted until there is a call to either CertCloseStore or CertControlStoreusing CERT_STORE_CTRL_COMMIT.

CERT_REGISTRY_STORE_REMOTE_FLAG

When this flag is set, the hKey passed in pvPara points to a registry key on a remote computer. To access a registry key on a remote computer, Security Permissions on the remote computer must be set to allow access. See the Remarks section for further details.

One HIWORD flag, CERT_FILE_STORE_COMMIT_ENABLE, has been added for the file provider types, CERT_STORE_PROV_FILE, and CERT_STORE_PROV_FILENAME.

When this flag is set, any additions to the store or any changes made to properties of contexts in the store are committed to the file store either when CertCloseStore is called or when CertControlStore is called with CERT_STORE_CONTROL_COMMIT.

CertOpenStore fails with E_INVALIDARG if both CERT_FILE_STORE_COMMIT_ENABLE and CERT_STORE_READONLY_FLAG are set in dwFlags.

pvPara

Pointer to a VOID that can point to data of different data types depending on which provider is being used. Detailed information about the type and content to be passed in pvPara is given in the descriptions of the available providers.

Return Values

If CertOpenStore fails, NULL is returned. Otherwise, a handle to the certificate store is returned.

GetLastError returns an error code if the function fails; however, CreateFile, ReadFile, or registry errors may be propagated and their error codes will be returned. CertOpenStore has a single error code of its own; ERROR_FILE_NOT_FOUND which indicates that the function was unable to find the provider specified by lpszStoreProvider parameter.

Remarks

A system store is a collection consisting of one or more physical sibling stores. For each system store, there are predefined physical sibling stores. After opening a system store such as MY at CERT_SYSTEM_STORE_CURRENT_USER, CertOpenStore is called to open of all of the physical stores in the system store collection. Each of these physical stores is added to the system store collection using CertAddStoreToCollection. All certificates, CRLs, and CTLs in those physical stores are available through the logical system store collection.

The following system store locations can be opened remotely:

CERT_SYSTEM_STORE_LOCAL_MACHINE

CERT_SYSTEM_STORE_SERVICES

CERT_SYSTEM_STORE_USERS

CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY

System store locations are opened remotely by prefixing the store name in the string passed to pvPara with the computer name. Examples of remote system store names are:

ComputerName\CA

\\ComputerName\CA

ComputerName\ServiceName\Trust

\\ComputerName\ServiceName\Trust

For additional information on system stores, see System Store Locations.

To access a remote store, the Security Permissions in the registry keys on the remote computer must be set to allow access. For more information on setting Security Permissions in an NT registry, see MDSN Article ID Q155363. For information on what to do to enable remote administration on a Win95 registry.

Example

//==================================================
// This code provides examples of opening the most
// common certificate stores.
// For additional examples, see Example Code for
// Opening a Certificate Store. 
//==================================================

// 1. Open the MY system store.
HCERTSTORE hSys_Store; 
hSys_Store = CertOpenStore(
   CERT_STORE_PROV_SYSTEM,   // The store provider type.
   0,                        // The encoding type is not needed.
   NULL,                     // Use the default HCRYPTPROV.
CERT_SYSTEM_STORE_CURRENT_USER,
// Set store location in a registry
// location.
L"MY"                     // The store name as a unicode string.
   );
// Substitute in other common system store names for "MY" 
// including "root", "trust", or "CA".
// Open a memory store. 
HCERTSTORE hMem_Store;
hMem_Store = CertOpenStore(
   CERT_STORE_PROV_MEMORY,   // The memory provider type.
   0,                        // The encoding type is not needed.
   NULL,                     // Use the default HCRYPTPROV. 
   0,                        // Accept the default dwFlags.
   NULL                      // pvPara not used.
   );

// Open a store from disk. In this example, the read only flag is set.
HANDLE       hFile;
HCERTSTORE   hFile_Store;
LPCSTR       pszFileName = "TestStor2.sto"
//  First, obtain a file handle.
if( !(hFile = CreateFile(
    pszFileName,                  // The file name
    GENERIC_READ|GENERIC_WRITE,   // Access mode: 
                                  // read from and write to this file
    0,                            // Share Mode
    NULL,                         // Security 
    OPEN_ALWAYS,                  // How to create
    FILE_ATTRIBUTE_NORMAL,        // File Attributes
    NULL)))                       // Template
{
printf("Could not open %s On Disk\n", pszFileName);
goto error_routine;
}
//   At this point, and data in the open file that precedes the
//   serialized cert store data may be used. The file pointer must
//   be placed at the beginning of the cert store data before 
//   CertOpenStore with the CERT_STORE_PROV_FILE provider is called.
//   Open the store
if ( ! (hFile_Store = CertOpenStore(
    CERT_STORE_PROV_FILE,     //  Load certificates from a file.
    0,                        //  Encoding type not used.
    NULL,                     //  Use the default HCRYPTPROV.
CERT_STORE_READONLY_FLAG  //  See the LOWORD of dwFlags to make
//  the store read only.
    hFile                     //  The handle for the open file 
                              //  that is the source of the 
                              //  certificates.
    )))
{
printf("Could not open the file store. \n");
goto error_routine;
}
// Include code to work with the certificates 
// The data file from which the certificate store information has been 
// read is still open. Any data in that file that follows the 
// serialized store can be read from the file and used at this point.  
// Close the file store and the file.
CertCloseStore(
hFile_Store, 
CERT_CLOSE_STORE_CHECK_FLAG);
CloseHandle(hFile);
error_routine:
//  Here include any code to be done if the disk file 
//  could not be opened

QuickInfo