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

Header file: Wincrypt.h
Windows CE versions: 2.10 and later

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.

PROV_RSA_FULL PROV_SSL
PROV_RSA_SIG PROV_EC_ECDSA_SIG
PROV_DSS PROV_EC_ECNRA_SIG
PROV_DSS_DH PROV_EC_ECDSA_FULL
PROV_FORTEZZA PROV_EC_ECNRA_FULL
PROV_MS_EXCHANGE PROV_SPYRUS_LYNKS
PROV_RSA_SCHANNEL  

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:

Flag Description
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 for the current user. The CRYPT_MACHINE_KEYSET flag can be set and combined with all of the other flags to indicate that the keys are persisted for the computer and not for any particular user. Combined with the CRYPT_NEWKEYSET flag, the CRYPT_MACHINE_KEYSET flag can access keys for a service.
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.

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.

Value Description
ERROR_INVALID_PARAMETER One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_NOT_ENOUGH_MEMORY The operating system ran out of memory during the operation.
NTE_BAD_FLAGS The dwFlags parameter has an illegal value.
NTE_BAD_KEYSET The key container could not be opened and may not exist.
NTE_BAD_KEYSET_PARAM The pszContainer or pszProvider parameter is set to an illegal value.
NTE_BAD_PROV_TYPE The value of the dwProvType parameter is out of range. All provider types must be from 1 to 999, inclusive.
NTE_BAD_SIGNATURE The provider DLL signature could not be verified. Either the DLL or the digital signature has been tampered with.
NTE_EXISTS The dwFlags parameter is CRYPT_NEWKEYSET, but the key container already exists.
NTE_FAIL The function failed in some unexpected way.
NTE_KEYSET_ENTRY_BAD The pszContainer key container was found but is corrupt.
NTE_KEYSET_NOT_DEF The key container specified by pszContainer does not exist.
NTE_NO_MEMORY The CSP ran out of memory during the operation.
NTE_PROV_DLL_NOT_FOUND The provider DLL file does not exist or is not on the current path.
NTE_PROV_TYPE_ENTRY_BAD The provider type specified by dwProvType is corrupt. This error may relate to either the user default CSP list or the machine default CSP list.
NTE_PROV_TYPE_NO_MATCH The provider type specified by dwProvType does not match the provider type found. Note that this error can only occur when pszProvider specifies an actual CSP name.
NTE_PROV_TYPE_NOT_DEF No entry exists for the provider type specified by dwProvType.
NTE_PROVIDER_DLL_FAIL The provider DLL file could not be loaded, and may not exist. If it exists, then the file is not a valid DLL.
NTE_SIGNATURE_FILE_BAD An error occurred while loading the DLL file image, prior to verifying its signature.

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