[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
);
| 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:
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.
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.
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.
pvPara should be set to NULL and the HIWORD of dwFlags set to 0.
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.
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.
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.
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.
A pointer to a CRYPT_DATA_BLOB serialized memory blob is passed in pvPara.
Additional store providers may be installed or registered via CryptInstallOIDFunctionAddress or CryptRegisterOIDFunction. For additional information, see Extending CertOpenStore Functionality.
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.
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 |
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.
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
Two addition HIWORD flags have been added for the CERT_STORE_PROV_REGISTRY provider.
CERT_REGISTRY_STORE_SERIALIZED_FLAG
CERT_REGISTRY_STORE_REMOTE_FLAG
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.
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.
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.
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.
//==================================================
// 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
Windows NT: Requires version 4.0 SP3 or later. Available also in IE 3.02 and later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Unsupported.
Header: Declared in wincrypt.h.
Import Library: Use crypt32.lib.
Example Code for Opening a Certificate Store, CertSaveStore, CertCloseStore.