Share via

CPAcquireContext (Compact 2013)

  • Article

3/28/2014

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

Syntax

BOOL CPAcquireContext(
  HCRYPTPROV* phProv,
  WCHAR* pszContainer,
  DWORD dwFlags,
  PVTableProvStruc pVTable 
);

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. UIs cannot be associated with these keys because they can be used by unattended server applications.

    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 freed 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 Value

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.

Error

Description

NTE_BAD_FLAGS

The dwFlags parameter has an illegal value.

NTE_BAD_KEYSET

The key container could not be opened and might not exist.

NTE_BAD_KEYSET_PARAM

The pszContainer parameter is set to an illegal value.

NTE_BAD_SIGNATURE

The digital signature of an auxiliary DLL did not verify correctly. 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_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_PROVIDER_DLL_FAIL

An auxiliary DLL file could not be loaded and might not exist. If it exists, the file is not a valid DLL.

Requirements

Header

wincrypt.h

Library

Developer Implemented

See Also

Reference

Cryptography Functions
CryptGenKey
CryptGetProvParam
CryptReleaseContext
CryptSetProvParam
CryptAcquireContext
CryptSetProvParam
SetLastError
VTableProvStruc