Export (0) Print
Expand All

CPAcquireContext (Windows CE 5.0)

Windows CE 5.0
Send Feedback

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

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 valueDescription
CRYPT_VERIFYCONTEXTThe 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_NEWKEYSETA 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_KEYSETBy 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_DELETEKEYSETThis 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_SILENTThis 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.

ErrorDescription
NTE_BAD_FLAGSThe dwFlags parameter has an illegal value.
NTE_BAD_KEYSETThe key container could not be opened and might not exist.
NTE_BAD_KEYSET_PARAMThe pszContainer parameter is set to an illegal value.
NTE_BAD_SIGNATUREThe digital signature of an auxiliary DLL did not verify correctly. Either the DLL or the digital signature has been tampered with.
NTE_EXISTSThe dwFlags parameter is CRYPT_NEWKEYSET, but the key container already exists.
NTE_KEYSET_ENTRY_BADThe pszContainer key container was found but is corrupt.
NTE_KEYSET_NOT_DEFThe key container specified by pszContainer does not exist.
NTE_NO_MEMORYThe CSP ran out of memory during the operation.
NTE_PROVIDER_DLL_FAILAn auxiliary DLL file could not be loaded and might not exist. If it exists, the file is not a valid DLL.

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


Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.


Show:
© 2014 Microsoft