CryptAcquireContext

This function is used to acquire a handle to a particular key container within a particular cryptographic service provider (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.

At a Glance

Syntax

BOOLEAN CRYPTFUNC CryptAcquireContext (HCRYPTPROV *phProv,
LPCTSTR pszContainer, LPCTSTR pszProvider, DWORD dwProvType,
DWORD dwFlags );

Parameters

phProv

[out] Address to which the function copies a handle to the CSP.

pszContainer

[in] Pointer to the null-terminated string that contains the key container name, which 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.

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

[in] Pointer to the null-terminated string that contains the provider name, which specifies the CSP to be used.

If this parameter is NULL then the user default provider is used. For more information about connecting to CSPs, see Cryptography.

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

[in] Specifies the type of provider to acquire. The following provider types are predefined.

dwFlags

[in] Specifies a bitmask of flags. This parameter is normally set to zero, but some applications set one or more of the following flags:

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.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

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;
}
 

Remarks

Windows CE does not support the ANSI version of this function.

See Also

CryptGenKey, CryptGetProvParam, CryptReleaseContext