CryptAcquireContext

The CryptAcquireContext function is used to acquire a handle to a particular key container within a particular CSP. This returned handle can then be used to make calls to the selected CSP.

This function performs two operations. It first attempts to find a CSP with the characteristics described in the dwProvType and pszProvider parameters. If the CSP is found, then the function attempts to find a key container within the CSP matching the name specified by the pszContainer parameter.

This function can also be used to create and destroy key containers, depending on the value of the dwFlags parameter.

#include <wincrypt.h>
BOOL WINAPI CryptAcquireContext(
  HCRYPTPROV *phProv,   // out
  LPCTSTR pszContainer, // in
  LPCTSTR pszProvider,  // in
  DWORD dwProvType,     // in
  DWORD dwFlags         // in
);
 

Parameters

phProv

Address to which the function copies a handle to the CSP.

pszContainer

Key container name. This is a zero-terminated string that identifies the key container to the CSP. This name is independent of the method used to store the keys. Some CSPs will store their key containers internally (in hardware), some will use the system registry, and others will use the file system. pszContainer is to be set to NULL when dwFlags is set to CRYPT_VERIFYCONTEXT.

If this parameter is NULL, then a default key container name will be used. For example, if the Microsoft Base Cryptographic Provider is being used, then the current user's logon name will be used as the name of the key container. Other CSPs may also have default key containers that can be acquired in this way.

An application can obtain the name of the acquired key container at a later time by reading the PP_CONTAINER CSP parameter with the CryptGetProvParam function.

pszProvider

Provider name. This is a zero-terminated string that specifies the CSP to be used.

If this parameter is NULL then the user default provider is used. For more details, see Connecting to a Cryptographic Service Provider.

An application can obtain the name of the acquired CSP at a later time by reading the PP_NAME CSP parameter with the CryptGetProvParam function.

dwProvType

Type of provider to acquire. The following provider types are predefined, and are discussed in detail in Interfacing with a Cryptographic Service Provider (CSP).

• PROV_RSA_FULL
• PROV_RSA_SIG
• PROV_DSS
• PROV_DSS_DH
• PROV_DH_SCHANNEL
• PROV_FORTEZZA
• PROV_MS_EXCHANGE
• PROV_RSA_SCHANNEL
• PROV_SSL

dwFlags

Flag values. This parameter is normally set to zero, but some applications will set one or more of the following flags:

• CRYPT_VERIFYCONTEXT. If this flag is set, then the application will have no access to the private keys and the pszContainer parameter must be set to NULL.

  This option is intended to be used with applications that will not be using private keys.

  When CryptAcquireContext is called, many CSPs will require input from the owning user before granting access to the private keys in the key container. For example, the private keys may be encrypted, requiring a password from the user before they can be used. However, if the CRYPT_VERIFYCONTEXT flag is specified, access to the private keys is not required and the user interface can be bypassed.

• CRYPT_NEWKEYSET. If this flag is set, then a new key container will be created with the name specified by pszContainer. If pszContainer is NULL, then a key container with the default name will be created. See CRYPT_MACHINE_KEYSET for information on combining flags.
• CRYPT_MACHINE_KEYSET. By default, keys are stored in the HKEY_CURRENT_USER portion of the registry. The CRYPT_MACHINE_KEYSET flag can be combined with all of the other flags, indicating that the location for the key of interest is HKEY_LOCAL_MACHINE. When combined with the CRYPT_NEWKEYSET flag, the CRYPT_MACHINE_KEYSET flag is useful when access is being performed from a service or user account that did not log on interactively. This combination enables access to user specific keys under HKEY_LOCAL_MACHINE.

Note  When key containers are created, most CSPs will not automatically create any public/private key pairs. These keys must be created as a separate step with the CryptGenKey function.

• CRYPT_DELETEKEYSET. If this flag is set, then the key container specified by pszContainer is deleted. If pszContainer is NULL, then the key container with the default name is deleted. All key pairs in the key container are also destroyed.

  When the CRYPT_DELETEKEYSET flag is set, the value returned in phProv is undefined and, thus, the CryptReleaseContext function need not be called afterwards.

Return Values

If the function succeeds, the return value is TRUE. If it does not succeed, the return value is FALSE. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
BYTE pbData[1000];
DWORD cbData;

// Get a handle to the default PROV_RSA_FULL provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
    printf("Error %x during CryptAcquireContext!\n", GetLastError());
    return;
}

// Read the name of the default CSP.
cbData = 1000;
if(!CryptGetProvParam(hProv, PP_NAME, pbData, &cbData, 0)) {
    printf("Error %x reading CSP name!\n", GetLastError());
    return;
}
printf("Provider name: %s\n", pbData);

// Read the name of the default key container.
cbData = 1000;
if(!CryptGetProvParam(hProv, PP_CONTAINER, pbData, &cbData, 0)) {
    printf("Error %x reading key container name!\n", GetLastError());
    return;
}
printf("Key Container name: %s\n", pbData);

// Perform cryptographic operations.
...

// Release the provider handle.
if(!CryptReleaseContext(hProv, 0)) {
    printf("Error %x during CryptReleaseContext!\n", GetLastError());
    return;
}

// ****************************************************************

// Get a handle to the Microsoft Base Cryptographic Provider and the 
// "KC1" key container.
if(!CryptAcquireContext(&hProv, TEXT("KC1"), MS_DEF_PROV, 
                        PROV_RSA_FULL, 0)) {
    printf("Error %x during CryptAcquireContext!\n", GetLastError());
    return;
}

// Perform cryptographic operations.
...

// Release the provider handle.
if(!CryptReleaseContext(hProv, 0)) {
    printf("Error %x during CryptReleaseContext!\n", GetLastError());
    return;
}

// ****************************************************************

// Get a handle to the default provider. Create a new key container 
// named "KC2". Note that this key container will be empty until keys
// are explicitly created with the CryptGenKey function.
lstrcpy(szProv, );
lstrcpy(szContainer, );
if(!CryptAcquireContext(&hProv, TEXT("KC2"), NULL, PROV_RSA_FULL,
                        CRYPT_NEWKEYSET)) {
    printf("Error %x during CryptAcquireContext!\n", GetLastError());
    return;
}

// Perform cryptographic operations.
...

// Release the provider handle.
if(!CryptReleaseContext(hProv, 0)) {
    printf("Error %x during CryptReleaseContext!\n", GetLastError());
    return;
}
 

For more examples, see Hashed Message Example Code, Enveloped Message Example 1, Enveloped Message Example 2, Sender Code Example, and Example Code Using CryptEncryptMessage.

QuickInfo

  Windows NT: Requires version 4.0 or later.
  Windows: Requires Windows 95 OSR2 or later (or Windows 95 with IE 3.02 or later).
  Windows CE: Unsupported.
  Header: Declared in wincrypt.h.
  Import Library: Use advapi32.lib.
  Unicode: Defined as Unicode and ANSI prototypes.

See Also

CryptGenKey, CryptGetProvParam, CryptReleaseContext