CARD_DATA structure

  • Article

The CARD_DATA structure contains context information used during communication between a smart card module and either the Microsoft base smart card Cryptographic Service Provider (CSP) or the smart card Key Storage Provider (KSP).

The structure includes pointers to all functions that the smart card module implements. It also includes pointers to the functions that the CSP and KSP export to the smart card module.

Syntax

typedef struct _CARD_DATA {
  DWORD                            dwVersion;
  PBYTE                            pbAtr;
  DWORD                            cbAtr;
  LPWSTR                           pwszCardName;
  PFN_CSP_ALLOC                    pfnCspAlloc;
  PFN_CSP_REALLOC                  pfnCspReAlloc;
  PFN_CSP_FREE                     pfnCspFree;
  PFN_CSP_CACHE_ADD_FILE           pfnCspCacheAddFile;
  PFN_CSP_CACHE_LOOKUP_FILE        pfnCspCacheLookupFile;
  PFN_CSP_CACHE_DELETE_FILE        pfnCspCacheDeleteFile;
  PVOID                            pvCacheContext;
  PFN_CSP_PAD_DATA                 pfnCspPadData;
  SCARDCONTEXT                     hSCardCtx;
  SCARDHANDLE                      hScard;
  PVOID                            pvVendorSpecific;
  PFN_CARD_DELETE_CONTEXT          pfnCardDeleteContext;
  PFN_CARD_QUERY_CAPABILITIES      pfnCardQueryCapabilities;
  PFN_CARD_DELETE_CONTAINER        pfnCardDeleteContainer;
  PFN_CARD_CREATE_CONTAINER        pfnCardCreateContainer;
  PFN_CARD_GET_CONTAINER_INFO      pfnCardGetContainerInfo;
  PFN_CARD_AUTHENTICATE_PIN        pfnCardAuthenticatePin;
  PFN_CARD_GET_CHALLENGE           pfnCardGetChallenge;
  PFN_CARD_AUTHENTICATE_CHALLENGE  pfnCardAuthenticateChallenge;
  PFN_CARD_UNBLOCK_PIN             pfnCardUnblockPin;
  PFN_CARD_CHANGE_AUTHENTICATOR    pfnCardChangeAuthenticator;
  PFN_CARD_DEAUTHENTICATE          pfnCardDeauthenticate;
  PFN_CARD_CREATE_DIRECTORY        pfnCardCreateDirectory;
  PFN_CARD_DELETE_DIRECTORY        pfnCardDeleteDirectory;
  LPVOID                           pvUnused3;
  LPVOID                           pvUnused4;
  PFN_CARD_CREATE_FILE             pfnCardCreateFile;
  PFN_CARD_READ_FILE               pfnCardReadFile;
  PFN_CARD_WRITE_FILE              pfnCardWriteFile;
  PFN_CARD_DELETE_FILE             pfnCardDeleteFile;
  PFN_CARD_ENUM_FILES              pfnCardEnumFiles;
  PFN_CARD_GET_FILE_INFO           pfnCardGetFileInfo;
  PFN_CARD_QUERY_FREE_SPACE        pfnCardQueryFreeSpace;
  PFN_CARD_QUERY_KEY_SIZES         pfnCardQueryKeySizes;
  PFN_CARD_SIGN_DATA               pfnCardSignData;
  PFN_CARD_RSA_DECRYPT             pfnCardRSADecrypt;
  PFN_CARD_CONSTRUCT_DH_AGREEMENT  pfnCardConstructDHAgreement;
  PFN_CARD_DERIVE_KEY              pfnCardDeriveKey;
  PFN_CARD_DESTROY_DH_AGREEMENT    pfnCardDestroyDHAgreement;
  PFN_CSP_GET_DH_AGREEMENT         pfnCspGetDHAgreement;
  PFN_CARD_GET_CHALLENGE_EX        pfnCardGetChallengeEx;
  PFN_CARD_AUTHENTICATE_EX         pfnCardAuthenticateEx;
  PFN_CARD_CHANGE_AUTHENTICATOR_EX pfnCardChangeAuthenticatorEx;
  PFN_CARD_DEAUTHENTICATE_EX       pfnCardDeauthenticateEx;
  PFN_CARD_GET_CONTAINER_PROPERTY  pfnCardGetContainerProperty;
  PFN_CARD_SET_CONTAINER_PROPERTY  pfnCardSetContainerProperty;
  PFN_CARD_GET_PROPERTY            pfnCardGetProperty;
  PFN_CARD_SET_PROPERTY            pfnCardSetProperty;
  PFN_CSP_UNPAD_DATA               pfnCspUnpadData;
  PFN_MD_IMPORT_SESSION_KEY        pfnMDImportSessionKey;
  PFN_MD_ENCRYPT_DATA              pfnMDEncryptData;
  PFN_CARD_IMPORT_SESSION_KEY      pfnCardImportSessionKey;
  PFN_CARD_GET_SHARED_KEY_HANDLE   pfnCardGetSharedKeyHandle;
  PFN_CARD_GET_ALGORITHM_PROPERTY  pfnCardGetAlgorithmProperty;
  PFN_CARD_GET_KEY_PROPERTY        pfnCardGetKeyProperty;
  PFN_CARD_SET_KEY_PROPERTY        pfnCardSetKeyProperty;
  PFN_CARD_DESTROY_KEY             pfnCardDestroyKey;
  PFN_CARD_PROCESS_ENCRYPTED_DATA  pfnCardProcessEncryptedData;
  PFN_CARD_CREATE_CONTAINER_EX     pfnCardCreateContainerEx;
} CARD_DATA, *PCARD_DATA;

Members

  • dwVersion
    The version number of the smart card minidriver.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function with the requested version.

    On output, this member must be set to the version of this structure that the smart card minidriver returns.

  • pbAtr
    The ATR string that identifies the smart card.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function.

  • cbAtr
    The size, in bytes, of the string contained in the pbAtr parameter.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function.

  • pwszCardName
    A pointer to a null-terminated wide character string that contains the name of the smart card.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function.

  • pfnCspAlloc
    A PFN_CSP_ALLOC function pointer.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function.

  • pfnCspReAlloc
    A PFN_CSP_ALLOC function pointer.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function.

  • pfnCspFree
    A PFN_CSP_FREE function pointer.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function.

  • pfnCspCacheAddFile
    A PFN_CSP_CACHE_ADD_FILE function pointer.

    This member must be initialized by the CSP or KSP after calling the CardAcquireContext function. Implementations of CardAcquireContext must check that this member is not set to NULL before using or caching the pointer.

  • pfnCspCacheLookupFile
    A PFN_CSP_CACHE_LOOKUP_FILE function pointer.

    This member must be initialized by the CSP or KSP after calling the CardAcquireContext function. Implementations of CardAcquireContext must check that this member is not set to NULL before using or caching the pointer.

  • pfnCspCacheDeleteFile
    A PFN_CSP_CACHE_DELETE_FILE function pointer.

    This member must be initialized by the CSP or KSP after calling the CardAcquireContext function. Implementations of CardAcquireContext must check that this member is not set to NULL before using or caching the pointer.

  • pvCacheContext
    A pointer to a context value used by the functions pointed to by the PFN_CSP_CACHE_ADD_FILE, PFN_CSP_CACHE_LOOKUP_FILE, and PFN_CSP_CACHE_DELETE_FILE function pointers.

    This member must be initialized by the CSP or KSP after calling the CardAcquireContext function. Implementations of CardAcquireContext must check that this member is not set to NULL before using or caching the pointer.

  • pfnCspPadData
    A PFN_CSP_PAD_DATA function pointer.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function.

  • hSCardCtx
    A handle that identifies the resource manager context. The CSP or KSP retrieves the resource manager context from a previous call to the SCardEstablishContext function.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function.

  • hScard
    A handle to a smart card. The CSP or KSP retrieves this handle from a previous call to the SCardConnect function.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function.

  • pvVendorSpecific
    A pointer to card-specific information that the smart card minidriver can use.

  • pfnCardDeleteContext
    A pointer to the CardDeleteContext function implemented by the smart card minidriver.

  • pfnCardQueryCapabilities
    A pointer to the CardQueryCapabilities function implemented by the smart card minidriver.

  • pfnCardDeleteContainer
    A pointer to the CardDeleteContainer function implemented by the smart card minidriver.

  • pfnCardCreateContainer
    A pointer to the CardCreateContainer function implemented by the smart card minidriver.

  • pfnCardGetContainerInfo
    A pointer to the CardGetContainerInfo function implemented by the smart card minidriver.

  • pfnCardAuthenticatePin
    A pointer to the CardAuthenticatePin function implemented by the smart card minidriver.

  • pfnCardGetChallenge
    A pointer to the CardGetChallenge function implemented by the smart card minidriver.

  • pfnCardAuthenticateChallenge
    A pointer to the CardAuthenticateChallenge function implemented by the smart card minidriver.

  • pfnCardUnblockPin
    A pointer to the CardUnblockPin function implemented by the smart card minidriver.

  • pfnCardChangeAuthenticator
    A pointer to the CardChangeAuthenticator function implemented by the smart card minidriver.

  • pfnCardDeauthenticate
    A pointer to the CardDeauthenticate function implemented by the smart card minidriver.

  • pfnCardCreateDirectory
    A pointer to the CardCreateDirectory function implemented by the smart card minidriver.

  • pfnCardDeleteDirectory
    A pointer to the CardDeleteDirectory function implemented by the smart card minidriver.

  • pvUnused3
    Reserved.

  • pvUnused4
    Reserved.

  • pfnCardCreateFile
    A pointer to the CardCreateFile function implemented by the smart card minidriver.

  • pfnCardReadFile
    A pointer to the CardReadFile function implemented by the smart card minidriver.

  • pfnCardWriteFile
    A pointer to the CardWriteFile function implemented by the smart card minidriver.

  • pfnCardDeleteFile
    A pointer to the CardDeleteFile function implemented by the smart card minidriver.

  • pfnCardEnumFiles
    A pointer to the CardEnumFiles function implemented by the smart card minidriver.

  • pfnCardGetFileInfo
    A pointer to the CardGetFileInfo function implemented by the smart card minidriver.

  • pfnCardQueryFreeSpace
    A pointer to the CardQueryFreeSpace function implemented by the smart card minidriver.

  • pfnCardQueryKeySizes
    A pointer to the CardQueryKeySizes function implemented by the smart card minidriver.

  • pfnCardSignData
    A pointer to the CardSignData function implemented by the smart card minidriver.

  • pfnCardRSADecrypt
    A pointer to the CardRSADecrypt function implemented by the smart card minidriver.

  • pfnCardConstructDHAgreement
    A pointer to the CardConstructDHAgreement function implemented by the smart card minidriver.

  • pfnCardDeriveKey
    A pointer to the CardDeriveKey function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v5.

  • pfnCardDestroyDHAgreement
    A

    pointer to the CardDestroyDHAgreement function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v5.

  • pfnCspGetDHAgreement
    A pointer to the PFN_CSP_GET_DH_AGREEMENT callback function set by the CSP.

    Supported in Smart Card Minidriver Specification v5.

  • pfnCardGetChallengeEx
    A pointer to the CardGetChallengeEx function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v6.

  • pfnCardAuthenticateEx
    A pointer to the CardAuthenticateEx function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v6.

  • pfnCardChangeAuthenticatorEx
    A pointer to the CardChangeAuthenticatorEx function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v6.

  • pfnCardDeauthenticateEx
    A pointer to the CardDeauthenticateEx function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v6.

  • pfnCardGetContainerProperty
    A pointer to the CardGetContainerProperty function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v6.

  • pfnCardSetContainerProperty
    A pointer to the CardSetContainerProperty function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v6.

  • pfnCardGetProperty
    A pointer to the CardGetProperty function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v6.

  • pfnCardSetProperty
    A pointer to the CardSetProperty function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v6.

  • pfnCspUnpadData
    A pointer to the CspUnpadData callback function set by the CSP.

    This member must be initialized by the CSP or KSP before calling the CardAcquireContext function.

    Supported in Smart Card Minidriver Specification v7.

  • pfnMDImportSessionKey
    A pointer to the MDImportSessionKey function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v7.

  • pfnMDEncryptData
    A pointer to the MDEncryptData function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v7.

  • pfnCardImportSessionKey
    A pointer to the CardImportSessionKey function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v7.

  • pfnCardGetSharedKeyHandle
    A pointer to the CardGetSharedKeyHandle function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v7.

  • pfnCardGetAlgorithmProperty
    A pointer to the CardGetAlgorithmProperty function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v7.

  • pfnCardGetKeyProperty
    A pointer to the CardGetKeyProperty function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v7.

  • pfnCardSetKeyProperty
    A pointer to the CardSetKeyProperty function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v7.

  • pfnCardDestroyKey
    A pointer to the CardDestroyKey function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v7.

  • pfnCardProcessEncryptedData
    A pointer to the CardProcessEncryptedData function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v7.

  • pfnCardCreateContainerEx
    A pointer to the CardCreateContainerEx function implemented by the smart card minidriver.

    Supported in Smart Card Minidriver Specification v7.

Remarks

Depending on the version the Smart Card Minidriver Specification with which the minidriver conforms, the function pointer members for the card functions implemented are set in this structure by the CardAcquireContext function.

Note  Smart card vendors must ensure that the ATR value (referenced through the pbAtr member) is unique for each card to avoid the erroneous pairing of a minidriver with a smart card. Multiple cards with different card-edges cannot have the same ATR value in the same system. Also, the ATR value must be sufficiently unique for Windows to load the appropriate card-specific minidriver. After applying the ATR mask, a card must be identifiable through a unique ATR. Windows expects the card to have the same ATR between resets. If the card changes the ATR value between warm or cold resets, the masked ATR values before and after the reset must match.

 

The pfnCardDeriveKey, pfnCardDestroyDHAgreement, and pfnCspGetDHAgreement members of the CARD_DATA structure are described in later sections. Starting with Smart Card Minidriver Specification v5.07, the necessary modifications to the pfnCardConstructDHAgreement function are handled through versioning the structure that is associated with that function.

If pfnCspPadData is NULL, the minidriver can expect that the calling application will not invoke a decrypt functionality.

We recommend that the minidriver issue a SELECT command for the desired application identifier (AID) on the card to ensure that the correct application is selected on the card if the card has multiple applications.

Requirements

Header

 Cardmod.h (include Cardmod.h)

 

 

Send comments about this topic to Microsoft