CPAcquireContext

This function acquires a handle to the key container specified by the pszContainer parameter.

BOOL CPAcquireContext(HCRYPTPROV* phProv,WCHAR* pszContainer,DWORDdwFlags,PVTableProvStrucpVTable);

Parameters

• phProv
  [out] Address to which the function copies a handle to the cryptographic service provider (CSP).

• pszContainer
  [in, out] Pointer to the null-terminated string of no more than MAX_PATH characters containing a key container name. The function ignores this parameter if CRYPT_VERIFYCONTEXT is set in dwFlags.

  If pszContainer is NULL or a zero length string on input, a default key container name is used. The Microsoft RSA Base Provider, for example, uses the logon name of the current user as the default key container name. Other CSPs can use different default key container names.

• dwFlags
  [in] Bitmask of flags. Can be zero. The following table shows possible flags for this parameter.

  Flag value	Description
  CRYPT_VERIFYCONTEXT	The application has no access to the private keys and the return pszContainer parameter must be set to NULL. This option is used with applications that do not use private keys. When CryptAcquireContext is called, many CSPs require input from the user before granting access to the private keys in the key container. For example, private keys might be encrypted, requiring a password from the user before being used. However, if CRYPT_VERIFYCONTEXT is specified and access to the private keys is not required, the user interface can be bypassed. When this flag is used and a public/private key pair is created or imported, that pair of keys is treated as treated as ephemeral; that is, the keys are kept only in memory and are automatically destroyed when CPReleaseContext is called.
  CRYPT_NEWKEYSET	A new key container is created with the name specified by pszContainer. If pszContainer is NULL on input, a key container with the default name is created. While a CSP is not required to create key pairs at this point; at the CSP author's discretion, a CSP can generate key pairs at this time. Keys are created through calls to CPGenKey, either within this call to CPAcquireContext or later as a separate step.
  CRYPT_MACHINE_KEYSET	By default, key containers and their keys are stored as keys associated with a specific user. For the CSP currently provided by Microsoft, user key containers are stored in the user's profile. The CRYPT_MACHINE_KEYSET flag is useful when access is being performed from a service or user account that did not log on interactively. The CRYPT_MACHINE_KEYSET flag can be combined with other flags indicating that the key container of interest is a machine key container and the CSP will treat it as such. For Microsoft CSPs, this means the keys are stored locally on the computer that created the key container. The CRYPT_MACHINE_KEYSET flag is used for keys that are machine keys that must be accessible to applications not associated with a user account. UI cannot be associated with these keys because they can be used by unattended server applications. With Microsoft CSPs, access-control lists (ACLs) can be set on these keys by using CPGetProvParam and CPSetProvParam with the PP_KEYSET_SEC_DESCR value. CSP writers can consider setting ACLs on keys as well. If a key container is to be a machine key container, the CRYPT_MACHINE_KEYSET flag must be used with all calls to CryptAcquireContext that reference the container. CRYPT_MACHINE_KEYSET applies specifically to the Microsoft provider types. Other provider types can store keys differently and can ignore this flag. All compatible CSPs must implement the CRYPT_MACHINE_KEYSET flag; however, simply ignoring the flag can do this implementation.
  CRYPT_DELETEKEYSET	This flag deletes the key container specified by pszContainer or, if pszContainer is NULL, the key container with the default name. All key pairs in the key container are also destroyed. After a key container has been deleted, the value returned in phProv is undefined; therefore, the context has been released and the application does not need to call CryptReleaseContext.
  CRYPT_SILENT	This flag directs the CSP to not display user interface (UI) for this context. If any future function call using this acquired CSP context requires UI to operate, the function call must fail and the function must set the last error to NTE_SILENT_CONTEXT. If CRYPT_SILENT is set and a later call is made to CPGenKey using CRYPT_USER_PROTECTED, that call will fail and the function must set the last error to NTE_SILENT_CONTEXT. This flag is intended for use with applications that cannot tolerate UI being displayed by the CSP.

• pVTable
  [in] Pointer to a VTableProvStruc structure containing a list of callback functions provided by the operating system for use by the CSP.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. The following table shows appropriate error codes that can be set using the SetLastError function.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Wincrypt.h.
Link Library: Developer defined.

See Also

CPGenKey | CPGetProvParam | CPReleaseContext | CPSetProvParam | CryptAcquireContext | CryptSetProvParam | SetLastError | VTableProvStruc

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.