CertOpenStore function (wincrypt.h)

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

Syntax

HCERTSTORE CertOpenStore(
  [in] LPCSTR            lpszStoreProvider,
  [in] DWORD             dwEncodingType,
  [in] HCRYPTPROV_LEGACY hCryptProv,
  [in] DWORD             dwFlags,
  [in] const void        *pvPara
);

Parameters

[in] lpszStoreProvider

A pointer to a null-terminated ANSI string that contains the store provider type.

The following values represent the predefined store types. The store provider type determines the contents of the pvPara parameter and the use and meaning of the high word of the dwFlags parameter. Additional store providers can be installed or registered by using the CryptInstallOIDFunctionAddress or CryptRegisterOIDFunction function. For more information about adding store providers, see Extending CertOpenStore Functionality.

[in] dwEncodingType

Specifies the certificate encoding type and message encoding type. Encoding is used only when the dwSaveAs parameter of the CertSaveStore function contains CERT_STORE_SAVE_AS_PKCS7. Otherwise, the dwMsgAndCertEncodingType parameter is not used.

This parameter is only applicable when the CERT_STORE_PROV_MSG, CERT_STORE_PROV_PKCS7, or CERT_STORE_PROV_FILENAME provider type is specified in the lpszStoreProvider parameter. For all other provider types, this parameter is unused and should be set to zero.

This parameter can be a combination of one or more of the following values.

[in] hCryptProv

This parameter is not used and should be set to NULL.

Windows Server 2003 and Windows XP:  A handle to a cryptographic provider. Passing NULL for 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 functions that verify the signature of a subject certificate or CRL.This parameter's data type is HCRYPTPROV.

[in] dwFlags

These values consist of high-word and low-word values combined by using a bitwise-OR operation.

The low-word portion of dwFlags controls a variety of general characteristics of the certificate store opened. This portion can be used with all store provider types. The low-word portion of dwFlags can be one of the following values.

The CERT_STORE_PROV_SYSTEM, CERT_STORE_PROV_SYSTEM_REGISTRY, and CERT_STORE_PROV_PHYSICAL provider types use the following high words of dwFlags to specify system store registry locations:

CERT_SYSTEM_STORE_CURRENT_SERVICE

CERT_SYSTEM_STORE_CURRENT_USER

CERT_SYSTEM_STORE_CURRENT_USER_GROUP_POLICY

CERT_SYSTEM_STORE_LOCAL_MACHINE

CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE

CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY

CERT_SYSTEM_STORE_SERVICES

CERT_SYSTEM_STORE_USERS

By default, a system store location is opened relative to the HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, or HKEY_USERS predefined registry key. For more information, see System Store Locations.

The following high-word flags override this default behavior.

The CERT_STORE_PROV_REGISTRY provider uses the following high-word flags.

The CERT_STORE_PROV_FILE and CERT_STORE_PROV_FILENAME provider types use the following high-word flags.

The CERT_STORE_PROV_LDAP provider type uses the following high-word flags.

[in] pvPara

A 32-bit value that can contain additional information for this function. The contents of this parameter depends on the value of the lpszStoreProvider and other parameters.

Return value

If the function succeeds, the function returns a handle to the certificate store. When you have finished using the store, release the handle by calling the CertCloseStore function.

If the function fails, it returns NULL. For extended error information, call GetLastError.

Remarks

A system store is a collection that consists 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 all of the physical stores in the system store collection. Each of these physical stores is added to the system store collection by using the CertAddStoreToCollection function. 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_LOCAL_MACHINE_GROUP_POLICY
• CERT_SYSTEM_STORE_SERVICES
• CERT_SYSTEM_STORE_USERS

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 more information about system stores, see System Store Locations.

For more information about the stores that are automatically migrated, see Certificate Store Migration.

Examples

The following example shows opening several certificate stores of different store provider types. The example uses the CreateMyDACL function, defined in the Creating a DACL topic, to ensure the open file is created with a proper DACL. For more examples of opening other store provider types, see Example C Code for Opening Certificate Stores.

//-------------------------------------------------------------------
// Open a system store, in this case, the My store.

HCERTSTORE hSysStore = NULL;
if(hSysStore = 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 the store location in a
                                    // registry location
   L"MY"                            // The store name as a Unicode 
                                    // string
   ))
{
    printf("The system store was created successfully.\n");
}
else
{
    printf("An error occurred during creation "
        "of the system store!\n");
    exit(1);
}

// Other common system stores include "Root", "Trust", and "Ca".


//-------------------------------------------------------------------
// Open a memory store. 

HCERTSTORE hMemStore = NULL;
if(hMemStore = 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 is not used
   ))
{
    printf("The memory store was created successfully.\n");
}
else
{
    printf("An error occurred during creation "
        "of the memory store!\n");
    exit(1);
}

//-------------------------------------------------------------------
// Open a read-only store from disk.

HANDLE       hFile = NULL;
HCERTSTORE   hFileStore = NULL;
LPCSTR       pszFileName = "TestStor2.sto";
SECURITY_ATTRIBUTES  sa;        // For DACL

// Create a DACL to use when opening the file.
sa.nLength = sizeof(SECURITY_ATTRIBUTES);
sa.bInheritHandle = FALSE;  

// Call function to set the DACL. The DACL is set in the 
// SECURITY_ATTRIBUTES lpSecurityDescriptor member.
if (!CreateMyDACL(&sa))
{
     // Error encountered; generate message and exit.
     printf("Failed CreateMyDACL.\n");
        exit(1);
}

// Obtain the file handle of an existing file.
if (hFile = CreateFile(
     pszFileName,                  // The file name
     GENERIC_READ|GENERIC_WRITE,   // Access mode: Read from and
                                   // write to this file
     0,                            // Share mode
     &sa,                          // Uses the DACL created 
                                   // previously 
     OPEN_ALWAYS,                  // How to create
     FILE_ATTRIBUTE_NORMAL,        // File attributes
     NULL))                        // Template
{
    printf("The file was opened successfully.\n");
}
else
{
    printf("An error occurred during opening of the file!\n");
    exit(1);
}

//-------------------------------------------------------------------
//  This file can contain data before the store itself.
//  At this point, read and use data in the open file that precedes
//  the serialized certificate store data. 
//  To open the certificate store, the file pointer must
//  be placed at the beginning of the certificate store data.

//-------------------------------------------------------------------
//  Open the store.

if(hFileStore = CertOpenStore(
    CERT_STORE_PROV_FILE,     // Load certificates from a file
    0,                        // Encoding type not used
    NULL,                     // Use the default HCRYPTPROV
    CERT_STORE_READONLY_FLAG, // Read-only store
    hFile                     // The handle for the open file 
                              // that is the source of the 
                              // certificates
    ))
{
    printf("The file store was created successfully.\n");
}
else
{
    printf("An error occurred during creation of the file store!\n");
    exit(1);
}

//-------------------------------------------------------------------
// After processing, close the certificate stores and the file.

if(CertCloseStore(
        hSysStore, 
        CERT_CLOSE_STORE_CHECK_FLAG))
{
    printf("The system store was closed successfully.\n");
}
else
{
    printf("An error occurred during closing of the "
        "system store.\n");
}

if(CertCloseStore(
        hMemStore, 
        CERT_CLOSE_STORE_CHECK_FLAG))
{
    printf("The memory store was closed successfully.\n");
}
else
{
    printf("An error occurred during closing of the "
        "memory store.\n");
}

if(CertCloseStore(
        hFileStore, 
        CERT_CLOSE_STORE_CHECK_FLAG))
{
    printf("The file store was closed successfully.\n");
}
else
{
    printf("An error occurred during closing of the file store.\n");
}

if(CloseHandle(hFile))
{
    printf("The file was closed successfully.\n");
}
else
{
    printf("An error occurred during closing of the file.\n");
}

Requirements

See also

CERT_SYSTEM_STORE_RELOCATE_PARA

CertCloseStore

CertSaveStore

Certificate Store Functions