CardAcquireContext function

Article
11/21/2017

The CardAcquireContext function is used to initialize communication between the Base CSP/KSP and the card minidriver. Upon return, pCardData points to a structure that is used to provide the context for most subsequent operations with the card minidriver.

Syntax

DWORD WINAPI CardAcquireContext(
  _Inout_ PCARD_DATA pCardData,
  _In_    DWORD      dwFlags
);

Parameters

pCardData [in, out]
Address of CARD_DATA structure, initialized by the Base CSP/KSP.
dwFlags [in]
A set of flags that modify the behavior of this function. Currently, only one flag is allowed. See 'Remarks'.

Return value

Zero on success; otherwise, nonzero. A list of expected error return values is shown 'Errors' (in addition to standard behavior described in “Error Handling” of Smart Card Minidriver Overview).

Remarks

The Base CSP/KSP initializes the structure and writes the Base CSP/KSP state and function table information before calling CardAcquireContext. The card minidriver adds its function table and state information to the structure and returns a status of zero if successful or a nonzero value if an error was encountered.

The Base CSP/KSP provides seven important function exports for the card minidriver to use:

Three for using the data caching mechanisms that the Base CSP/KSP provides.
Three to manage memory allocation.
One for removal of padding during decryption.

Many card minidriver functions transfer buffers between the Base CSP/KSP and the card minidriver by using a structure that contains a byte pointer. Memory is allocated by the party that generates the data and freed by the consumer of that data unless the description in this specification dictates otherwise. The card minidriver allocates and frees memory by calling the three memory management functions that the Base CSP/KSP defines.

The dwVersion member of the CARD_DATA structure is taken as an input when CardAcquireContext is called and is the desired version structure to be returned. To eventually support the loading of existing RSA card minidrivers, older versions may have to be loaded and recognized as such.

CardAcquireContext must accept 0 for dwFlags when Secure Key Injection is not supported or requested.

CardAcquireContext can be called with CARD_SECURE_KEY_INJECTION_NO_CARD_MODE set in dwFlags if context must be initialized for secure key Injection calls in server mode.

#define CARD_SECURE_KEY_INJECTION_NO_CARD_MODE  0x1

This flag instructs the minidriver not to expect any card in the reader. This implies that the answer-to-Reset (ATR) fields in pCardData is not filled. The hSCard and hSCardCtx members of the CARD_DATA structure is NULL.

When this flag is set, the minidriver can accept only the following function calls:

All other functions must return SCARD_E_INVALID_PARAMETER when CardAcquireContext is called with _SECURE_KEY_INJECTION_NO_CARD_MODE set in dwFlags.

For more information see Secure Key Injection.

Note The smart card minidriver must not assume a single context to manage communications with the card.

Errors

When passing an invalid pbAtr member to CardAcquireContext, the minidriver should return SCARD_E_UNKNOWN_CARD.

The minidriver should return the following errors if dwFlags is 0:

When passing NULL as pbAtr in the CARD_DATA structure, it should return SCARD_E_INVALID_PARAMETER.
When passing NULL for the card name (pwszCardName) in the CARD_DATA structure, it should return SCARD_E_INVALID_PARAMETER.
When passing invalid value (any correct length) in the pbAtr member in the CARD_DATA structure, it should return SCARD_E_INVALID_PARAMETER. If the value of the cbAtr field parameter is valid but is not of a known card, SCARD_E_UNKNOWN_CARD must be returned.

If CARD_SECURE_KEY_INJECTION_NO_CARD_MODE is set in dwFlags and the minidriver does not support this flag, the minidriver should return SCARD_E_UNSUPPORTED_FEATURE.

When passing a valid pbAtr to the wrong card minidriver, it should return SCARD_E_UNKNOWN_CARD.

When passing NULL for pfnCspAlloc, pfnCspReAlloc, or pfnCspFree callbacks, SCARD_E_INVALID_PARAMETER should be returned.

If the hSCardCtx and hSCard handles are set to NULL, the minidriver should return SCARD_E_INVALID_HANDLE unless CARD_SECURE_KEY_INJECTION_NO_CARD_MODE is set in dwFlags.

In addition, the conventions for smart card minidrivers must be followed. For more information, see the “Conventions” section in Smart Card Minidriver Overview

Requirements

Target platform	Desktop
Version	Supported in Smart Card Minidriver Specification v4.
Header	Cardmod.h (include Cardmod.h)

Share via