CryptAcquireContext

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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.

Syntax

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_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, key containers are stored in the HKEY_CURRENT_USER registry hive. The CRYPT_MACHINE_KEYSET flag can be set and combined with all of the other flags to indicate that the key container is stored in the HKEY_LOCAL_MACHINE hive instead.
  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 Value

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.

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 Embedded 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

See Also

Reference

CryptGenKey
CryptGetProvParam
CryptReleaseContext

Other Resources

Cryptography