CertOpenStore

Article
06/30/2006

This function opens a certificate store using a specified store provider type. While this function can open a certificate store for ordinary purposes, the CertOpenSystemStore function is recommended to open the most common certificate stores. The CertOpenStore function is required for more complex options and special cases.

HCERTSTORE WINAPI CertOpenStore(
  LPCSTR lpszStoreProvider,
  DWORD dwMsgAndCertEncodingType,
  HCRYPTPROV hCryptProv, 
  DWORD dwFlags, 
  const void* pvPara
);

Parameters

lpszStoreProvider
[in] Long pointer to a null-terminated string that contains the store provider type. The following list shows the predefined store provider types that furnish most common application needs:

CERT_STORE_PROV_FILE
CERT_STORE_PROV_MEMORY
CERT_STORE_PROV_PHYSICAL
CERT_STORE_PROV_PKCS7
CERT_STORE_PROV_REG
CERT_STORE_PROV_SERIALIZED
CERT_STORE_PROV_SYSTEM
CERT_STORE_PROV_SYSTEM_REGISTRY

Most of the provider names passed to the lpszStoreProvider parameter can 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 the pvPara parameter have alternate forms: one that passes the string as Unicode with an LPCWSTR variable and another that passes the string as ASCII with an LPCSTR variable. The names of providers that pass ASCII strings must be suffixed with _A as in CERT_STORE_PROV_FILENAME_A. The names of providers that pass Unicode strings can be suffixed with _W as in sz_CERT_STORE_PROV_REG_W. The names of providers without either the _A or _W use the default, Unicode form.

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

The following table shows store provider types that are defined.

Store provider	Description	pvPara use	Comment
CERT_STORE_PROV_FILE	Initializes the store with certificates 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 the CreateFile function.	The file pointer must 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 can follow the serialized store data in the file. If CERT_FILE_STORE_COMMIT_ENABLE is set in the dwFlags parameter, 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. Note that in Windows CE the file handle is not duplicated, so the caller should not close the file handle until the corresponding the CertCloseStore function has been called.
CERT_STORE_PROV_MEMORY	Creates a certificate store in cached memory. No certificates are initially loaded into the store. Typically used to create a temporary store.	Not used.	Additional certificates or changes in properties of certificates in a memory store are not automatically saved. They can be saved to a file or to a memory BLOB using the CertSaveStore function.
CERT_STORE_PROV_PHYSICAL	Initializes the store with certificates from a specified physical store that is a member of a logical system store.	Both the system store name and physical names.	Two names are separated with an intervening backslash (\): 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 cannot contain any backslashes. The high word of the dwFlags parameter indicates the system store location, usually CERT_SYSTEM_STORE_CURRENT_USER. For more information, see the dwFlags parameter. Some physical store locations can be opened remotely.
CERT_STORE_PROV_PKCS7	Initializes the store with certificates from an encoded PKCS #7 signed message.	Pointer to the CRYPT_DATA_BLOB of an encoded message	The dwMsgAndCertEncodingType parameter must specify the encoding types to be used with both messages and certificates.
CERT_STORE_PROV_REG	Initializes the store with certificates from a registry subkey.	The handle of an open registry key, named with the prefix HKEY.	This provider opens or creates the registry subkeys Certificates under the key passed in the pvPara parameter. The input key is not closed by the provider. Before returning, the provider opens its own copy of the key passed in the pvPara parameter. If CERT_STORE_READONLY_FLAG is set in the low word of the dwFlags parameter, registry subkeys are opened using RegOpenKey with KEY_READ_ACCESS. Otherwise, registry subkeys are created using 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 low word of the dwFlags parameter, any attempt to add to the contents of the store or to change a context's property results in an error with the GetLastError function returning the E_ACCESSDENIED code.
CERT_STORE_PROV_SERIALIZED	Initializes the store with certificates from a memory location containing a serialized store.	Pointer to a CRYPT_DATA_BLOB serialized memory BLOB.	Not applicable.
CERT_STORE_PROV_SYSTEM	Initializes the store with certificates from the specified system store.	A system store name passed as a Unicode or ASCII string, such as MY or Root.	The system store is a logical, collection store consisting of one or more physical stores. After the system store is opened, all of the physical stores that are associated with it are also opened by calls to the CertOpenStore function. The high word of the dwFlags parameter indicates the system store location, usually set to CERT_SYSTEM_STORE_CURRENT_USER. For more information on support for logical stores in Windows CE, see System Store Locations.
CERT_STORE_PROV_SYSTEM_REGISTRY	Initializes the store with certificates from a physical registry store. The physical store is not opened as a collection store. Enumerations and searches go through only the certificates in that one physical store. The implementation of this provider is the same as the CERT_STORE_PROV_SYSTEM provider implemented in Windows® NT 4.0.	A system store name, passed as a Unicode or ASCII string, such as MY or Root.	The high word of the dwFlags parameter indicates the system store location, usually set to CERT_SYSTEM_STORE_CURRENT_USER. For more information, see the dwFlags parameter. Some system store locations can be open remotely. For details, see System Store Locations.

Additional store providers can be installed by using the CryptInstallOIDFunctionAddress function.

dwMsgAndCertEncodingType
[in] Not used and should be set to zero.
hCryptProv
[in] Handle to a cryptographic provider. Passing NULL in this parameter causes an appropriate, default provider to be used. Using the default provider is recommended. The default or specified cryptographic provider is used for all store APIs that verify the signature of a subject certificate.

dwFlags
[in] High-word and low-word values combined using a bitwise OR operation.

The low-word portion of the dwFlags parameter controls a variety of general characteristics of the certificate store opened. This portion can be used with all store provider types. The following table shows low-word values that are currently defined.

Value	Description
CERT_STORE_CREATE_NEW_FLAG	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_DEFER_CLOSE_UNTIL_LAST_FREE_FLAG	The closing of a store's provider cannot be done when the CertCloseStore function is called but will be deferred if certificates obtained from the store are still in use. The store is actually closed when the last certificate obtained from the store is freed. Any changes made to properties of these certificates, even after the call to the CertCloseStore function, are persisted. If this flag is not set and certificates obtained from the store are still in use, the properties of those certificates can be changed, but those changes are not persisted. Setting this flag causes those changes to be persisted. Note that setting this flag causes extra overhead in doing context duplications and free operations. If the CertCloseStore function 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 the CertCloseStore function.
CERT_STORE_DELETE_FLAG	The store is deleted instead of being opened. The CertOpenStore function returns NULL for both success and failure of the deletion. To determine the success of the deletion, call the GetLastError function, which returns zero if the store was deleted and a nonzero value if it was not deleted.
CERT_STORE_ENUM_ARCHIVED_FLAG	Overrides the default procedure of skipping in enumerations all certificates with the CERT_ARCHIVED_PROP_ID property set. If this flag is set, an enumeration of the certificates in the store lists all of the certificates in the store, including those that have the CERT_ARCHIVED_PROP_ID property.
CERT_STORE_MANIFOLD_FLAG	Certificates are checked for their manifold extension. When certificates are found with the same manifold extension, the older certificates are archived by setting their CERT_ARCHIVED_PROP_ID properties.
CERT_STORE_NO_CRYPT_RELEASE_FLAG	This flag is not used when the NULL is passed in the hCryptProv parameter and the default CSP is used. The flag is valid when a non-NULL CSP handle is passed as the hCryptProv parameter. Setting the flag prevents the automatic release of a nondefault CSP when the certificate store is closed.
CERT_STORE_OPEN_EXISTING_FLAG	Only an existing store can be opened. If the store does not exist, the function fails.
CERT_STORE_READONLY_FLAG	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 by using RegOpenKey with KEY_READ_ACCESS. Otherwise, the registry subkeys are created by using RegCreateKey with KEY_ALL_ACCESS.
CERT_STORE_SET_LOCALIZED_NAME_FLAG	If this flag is supported, the provider sets the store's CERT_STORE_LOCALIZED_NAME_PROP_ID property. The localized name can be retrieved by calling the CertGetStoreProperty function with the dwPropID parameter set to CERT_STORE_LOCALIZED_NAME_PROP_ID. This flag is supported for providers of types CERT_STORE_PROV_FILENAME, CERT_STORE_PROV_SYSTEM, CERT_STORE_PROV_SYSTEM_REGISTRY, and CERT_STORE_PROV_PHYSICAL_W.
CERT_STORE_UPDATE_KEYID_FLAG	Within CurrentUser and LocalMachine, lists of key identifiers exist. These key identifiers have properties much like the properties of certificates. If the CERT_STORE_UPDATE_KEYID_FLAG is set, then for every key identifier in the store's location that has a CERT_KEY_PROV_INFO_PROP_ID property, that property is automatically updated from the key identifier property CERT_KEY_PROV_INFO_PROP_ID or the CERT_KEY_IDENTIFIER_PROP_ID of the certificate related to that key identifier.

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

CERT_SYSTEM_STORE_CURRENT_USER

CERT_SYSTEM_STORE_LOCAL_MACHINE

For more information, see System Store Locations.

The following table shows additional system store flags that can be set in the high-word value of the dwFlags parameter.

Value	Description
CERT_SYSTEM_STORE_RELOCATE_FLAG	Overrides the default location of a system store. When it is set, the pvPara parameter must pass a pointer to a CERT_SYSTEM_STORE_RELOCATE_PARA structure rather than a string. The 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 the CertOpenStore function 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.

One high-word 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 the CertCloseStore function is called or when the CertControlStore function is called with CERT_STORE_CONTROL_COMMIT.

The CertOpenStore function fails with E_INVALIDARG if both CERT_FILE_STORE_COMMIT_ENABLE and CERT_STORE_READONLY_FLAG are set in the dwFlags parameter.

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

Return Values

If the function succeeds, the return value is a handle to the certificate store.

If the function fails, the return value is NULL.

The CreateFile function, the ReadFile function, or registry errors might be propagated and their error codes returned. The CertOpenStore function 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 the 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, the CertOpenStore function is called to open of all of the physical stores in the system store collection. All certificates in those physical stores are available through the logical system store collection.

Windows CE does not support remote access to system stores. The desktop platform supports the flag PKCS_7_ASN_ENCODING, but Windows CE does not and ignores the flag when it is specified.

The desktop platform supports the following lpzStoreProvider flags that Windows CE does not support:

CERT_STORE_PROV_COLLECTION

CERT_STORE_PROV_FILENAME

CERT_STORE_PROV_LDAP

CERT_STORE_PROV_MSG

CERT_STORE_PROV_PKCS7

The desktop platform supports the following defined high-word values associated with system store providers that Windows CE does not support:

CERT_SYSTEM_STORE_CURREN_USER_GROUP_POLICY

CERT_SYSTEM_STORE_CURRENT_SERVICE

CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE

CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY

CERT_SYSTEM_STORE_SERVICES

CERT_SYSTEM_STORE_USERS

Requirements

OS Versions: Windows CE 3.0 and later.
Header: Wincrypt.h.
Link Library: Crypt32.lib.

Share via

CertOpenStore

Parameters

Return Values

Remarks

Requirements

See Also

Additional resources