CryptAcquireContext (Windows CE 5.0)

Article
09/14/2012

This function acquires a handle to a specific key container within a particular cryptographic service provider (CSP). This handle can be used to make calls to the selected CSP.

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

Parameters

phProv
[out] Pointer to a handle to a CSP.
pszContainer
[in] Pointer to a null-terminated string that identifies the key container to the CSP. This name is independent of the method used to store the keys. Some CSPs store their key containers internally in the hardware, some use the system registry, and others use the file system.

When dwFlags is set to CRYPT_VERIFYCONTEXT, pszContainer must be set to NULL. If this parameter is NULL, a default key container name is used.

Application developers should be carefull when using the default key container. When multiple applications use the same container, one application can change or destroy the keys that another application needs.

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 a null-terminated string that specifies the name of the CSP to be used.

If this parameter is NULL, the user default provider is used. For more information about connecting to CSPs, see the programmer's guide topics under 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_RSA_SIG
- PROV_DSS
- PROV_DSS_DH
- PROV_FORTEZZA
- PROV_MS_EXCHANGE
- PROV_RSA_SCHANNEL
- PROV_SSL
- PROV_EC_ECDSA_SIG
- PROV_EC_ECNRA_SIG
- PROV_EC_ECDSA_FULL
- PROV_EC_ECNRA_FULL
- PROV_SPYRUS_LYNKS
- PROV_RNG
- PROV_INTEL_SEC

dwFlags
[in] Bitmask of flags. This parameter is usually set to zero. The following table shows flags that can be set.

Flag	Description
CRYPT_VERIFYCONTEXT	If this flag is set, the application has no access to the private keys and the pszContainer parameter must be set to NULL. This option is intended for applications that do not use private keys. When CryptAcquireContext is called, many CSPs 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, a new key container is created with the name specified by pszContainer. If pszContainer is NULL, a key container with the default name is 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; therefore, a call to the CryptReleaseContext function is not required.
CRYPT_SILENT	The application requests that the CSP not display any user interface (UI) for this context. If the CSP must display the UI to operate, the call fails with the NTE_SILENT_CONTEXT error. In addition, if a call is made to CryptGenKey with the CRYPT_USER_PROTECTED flag and a context acquired with the CRYPT_SILENT flag, the call fails and the CSP sets NTE_SILENT_CONTEXT. CRYPT_SILENT is intended for CSP applications that cannot display a UI.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the GetLastError function.

The following table shows common values for the GetLastError function. The error values prefaced by NTE are generated by the particular CSP you are using.

Value	Description
ERROR_BUSY	Some CSPs set this error if the CRYPT_DELETEKEYSET flag value is set and another thread or process is using this key container.
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 contains an invalid value.
NTE_BAD_KEYSET	The key container could not be opened. A common cause of this error is that the key container does not exist. To create a key container, call CryptAcquireContext using the CRYPT_NEWKEYSET flag. This error code can also indicate that the access to an existing key container is denied.
NTE_BAD_KEYSET_PARAM	The pszContainer or pszProvider parameter is set to an invalid 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 Code

The following example shows a call to acquire a cryptographic context and to access public and private key pairs in a key container. If the requested key container does not exist, it is created.

//--------------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV hCryptProv = NULL;        // Handle for a cryptographic
                                     // provider context.
LPCSTR UserName = "MyKeyContainer";  // Name of the key container
                                     // to be used.
//--------------------------------------------------------------------
// Attempt to acquire a context and a key
// container. The context will use the default CSP
// for the RSA_FULL provider type. DwFlags is set to 0
// to attempt to open an existing key container.

if(CryptAcquireContext(
   &hCryptProv,               // Handle to the CSP.
   UserName,                  // Container name.
   NULL,                      // Use the default provider.
   PROV_RSA_FULL,             // Provider type.
   0))                        // Flag values.
{
    printf("A crypto context with the %s key container \n", UserName);
    printf("has been acquired.\n\n");
}
else
{ 
//--------------------------------------------------------------------
// An error occurred in acquiring the context. This could mean
// that the key container requested does not exist. In this case,
// the function can be called again to attempt to create a new key 
// container. Error codes are defined in winerror.h.
 if (GetLastError() == NTE_BAD_KEYSET)
 {
   if(CryptAcquireContext(
      &hCryptProv, 
      UserName, 
      NULL, 
      PROV_RSA_FULL, 
      CRYPT_NEWKEYSET)) 
    {
      printf("A new key container has been created.\n");
    }
    else
    {
      printf("Could not create a new key container.\n");
      exit(1);
    }
  else
  {
      printf("A cryptographic service handle could not be acquired.\n");
      exit(1);
   }
  
} // End of else.
//--------------------------------------------------------------------
// A cryptographic context and a key container are available. Perform
// any functions that require a Cryptographic provider handle.

//--------------------------------------------------------------------
// When the handle is no longer needed, it must be freed.

if (CryptReleaseContext(hCryptProv,0))
{
  printf("The handle has been freed.\n");
}
else
{
  printf("The handle could not be freed.\n");
}

Remarks

CryptAcquireContext performs two operations. First, it attempts to find a CSP with the characteristics described in the dwProvType and pszProvider parameters. Then, if the CSP is found, the function attempts to find a key container within the CSP matching the name specified by the pszContainer parameter. To acquire the context and the key container or a private key associated with the public key of a certificate, use the CryptAcquireCertificatePrivateKey function.

With the appropriate dwFlags setting, this function can also create and destroy key containers and can provide access to a CSP with a temporary key container if access to a private key is not required.

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

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

Requirements

OS Versions: Windows CE 2.10 and later.
Header: Wincrypt.h.
Link Library: Coredll.lib.