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.

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.

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.

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CryptGenKey, CryptGetProvParam, CryptReleaseContext

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.