SAMV71 Xplained Ultra Software Package 1.3

cciddriver.h

Go to the documentation of this file.
00001 /* ----------------------------------------------------------------------------
00002  *         ATMEL Microcontroller Software Support
00003  * ----------------------------------------------------------------------------
00004  * Copyright (c) 2008, Atmel Corporation
00005  *
00006  * All rights reserved.
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *
00011  * - Redistributions of source code must retain the above copyright notice,
00012  * this list of conditions and the disclaimer below.
00013  *
00014  * Atmel's name may not be used to endorse or promote products derived from
00015  * this software without specific prior written permission.
00016  *
00017  * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR
00018  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00019  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00020  * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
00021  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00022  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
00023  * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00024  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00025  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
00026  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00027  * ----------------------------------------------------------------------------
00028  */
00029 
00030 /**------------------------------------------------------------------------------
00031  * \file
00032  *
00033  * \section Purpose
00034  *
00035  * Definition of methods for using a CCID device driver.
00036  *
00037  * \section Usage
00038  *
00039  * -# CCIDDriver_Initialize
00040  * -# CCID_Read
00041  * -# CCID_Write
00042  * -# CCID_SmartCardRequest
00043  * -# CCID_Insertion
00044  * -# CCID_Removal
00045  * -# RDRtoPCHardwareError
00046  */
00047 
00048 #ifndef CCID_DRIVER_H
00049 #define CCID_DRIVER_H
00050 
00051 /** \addtogroup usbd_ccid
00052  *@{
00053  */
00054 /** For reference, the absolute maximum block size */
00055 /** for a TPDU T=0 block is 260 bytes (5 bytes command; 255 bytes data), or */
00056 /** for a TPDU T=1 block is 259 bytes, or */
00057 /** for a short APDU T=1 block is 261 bytes, or */
00058 /** for an extended APDU T=1 block is 65544 bytes. */
00059 #define ABDATA_SIZE 260
00060 
00061 /** define protocol T=0 */
00062 #define PROTOCOL_TO 0
00063 /** define protocol T=1 */
00064 #define PROTOCOL_T1 1
00065 
00066 /** define for dwFeatures see Table 5.1-1 Smart Card Device Class Descriptors */
00067 /** No special characteristics */
00068 #define CCID_FEATURES_NADA       0x00000000
00069 /** Automatic parameter configuration based on ATR data */
00070 #define CCID_FEATURES_AUTO_PCONF 0x00000002
00071 /** Automatic activation of ICC on inserting */
00072 #define CCID_FEATURES_AUTO_ACTIV 0x00000004
00073 /** Automatic ICC voltage selection */
00074 #define CCID_FEATURES_AUTO_VOLT  0x00000008
00075 /** Automatic ICC clock frequency change according to active parameters provided */
00076 /** by the Host or self determined */
00077 #define CCID_FEATURES_AUTO_CLOCK 0x00000010
00078 /** Automatic baud rate change according to active parameters provided by the */
00079 /** Host or self determined */
00080 #define CCID_FEATURES_AUTO_BAUD  0x00000020
00081 /** Automatic parameters negotiation made by the CCID (use of warm or cold */
00082 /** resets or PPS according to a manufacturer proprietary algorithm to select */
00083 /** the communication parameters with the ICC) */
00084 #define CCID_FEATURES_AUTO_PNEGO 0x00000040
00085 /** Automatic PPS made by the CCID according to the active parameters */
00086 #define CCID_FEATURES_AUTO_PPS   0x00000080
00087 /** CCID can set ICC in clock stop mode */
00088 #define CCID_FEATURES_ICCSTOP    0x00000100
00089 /** NAD value other than 00 accepted (T=1 protocol in use) */
00090 #define CCID_FEATURES_NAD        0x00000200
00091 /** Automatic IFSD exchange as first exchange (T=1 protocol in use) */
00092 #define CCID_FEATURES_AUTO_IFSD  0x00000400
00093 /** TPDU level exchanges with CCID */
00094 #define CCID_FEATURES_EXC_TPDU   0x00010000
00095 /** Short APDU level exchange with CCID */
00096 #define CCID_FEATURES_EXC_SAPDU  0x00020000
00097 /** Short and Extended APDU level exchange with CCID */
00098 #define CCID_FEATURES_EXC_APDU   0x00040000
00099 /** USB Wake up signaling supported on card insertion and removal */
00100 #define CCID_FEATURES_WAKEUP     0x00100000
00101 
00102 /*------------------------------------------------------------------------------ 
00103  *         Types                                                                
00104  *------------------------------------------------------------------------------*/
00105 
00106 #pragma pack(1)
00107 #if defined   ( __CC_ARM   ) /* Keil ¦ΜVision 4 */
00108 #elif defined ( __ICCARM__ ) /* IAR Ewarm 5.41+ */
00109 #define __attribute__(...)
00110 #elif defined (  __GNUC__  ) /* GCC CS3 2009q3-68 */
00111 #endif
00112 
00113 /**
00114  * \typedef S_ccid_bulk_in_header
00115  * \brief Bulk CCID Message header structure 
00116  */
00117 typedef struct _S_ccid_bulk_in_header
00118 {
00119    unsigned char bMessageType;
00120    /** Message-specific data length */
00121    unsigned long wLength;
00122    /** Identifies the slot number for this command */
00123    unsigned char bSlot;
00124    /** Sequence number for command. */
00125    unsigned char bSeq;
00126    /** Slot status register */
00127    unsigned char bStatus;
00128    /** Slot error */
00129    unsigned char bError;
00130    /** specific register */
00131    unsigned char bSpecific;
00132    /** Data block sent to the CCID. */
00133    unsigned char abData[ABDATA_SIZE];
00134    unsigned char bSizeToSend;
00135 } __attribute__ ((packed)) S_ccid_bulk_in_header;
00136 
00137 /**
00138  * \typedef S_ccid_bulk_out_header
00139  * \brief  6.1 Bulk Transfers 
00140  */
00141 typedef struct _S_ccid_bulk_out_header
00142 {
00143    unsigned char bMessageType;
00144    /** Message-specific data length */
00145    unsigned long wLength;
00146    /** Identifies the slot number for this command */
00147    unsigned char bSlot;
00148    /** Sequence number for command. */
00149    unsigned char bSeq;
00150    /** specific register */
00151    unsigned char bSpecific_0;
00152    unsigned char bSpecific_1;
00153    unsigned char bSpecific_2;
00154    /** Application Protocol Data Unit */
00155    unsigned char APDU[ABDATA_SIZE];
00156 } __attribute__ ((packed)) S_ccid_bulk_out_header;
00157 
00158 
00159 /**
00160  * \typedef S_ccid_PIN_Verification
00161  * \brief 6.1.11.2 PIN Verification Data Structure 
00162  */
00163 typedef struct _S_ccid_PIN_Verification
00164 {
00165     /** Number of seconds. */
00166     unsigned char bTimerOut;
00167     /** Several parameters for the PIN format options */
00168     unsigned char bmFormatString;
00169     /** Define the length of the PIN to present in the APDU command */
00170     unsigned char bmPINBlockString;
00171     /** Allows the length PIN insertion in the APDU command */
00172     unsigned char bmPINLengthFormat;
00173     /** Minimum PIN size in digit and Maximum PIN size in digit */
00174     unsigned char wPINMaxExtraDigit;
00175     /** The value is a bit wise OR operation. */
00176     unsigned char bEntryValidationCondition;
00177     /** Number of messages to display for the PIN modify command */
00178     unsigned char bNumberMessage;
00179     /** Language used to display the messages. */
00180     unsigned char wLangId;
00181     /** Message index in the Reader message table */
00182     unsigned char bMsgIndex;
00183     /** T=1 I-block prologue field to use */
00184     unsigned char bTeoPrologue[3];
00185     /** APDU to send to the ICC */
00186     unsigned char abPINApdu[255];
00187 }__attribute__ ((packed)) S_ccid_PIN_Verification;
00188 
00189 
00190 /**
00191  * \typedef S_ccid_PIN_Modification
00192  * \brief 6.1.11.7 PIN Modification Data Structure 
00193  */
00194 typedef struct _S_ccid_PIN_Modification
00195 {
00196     /** Number of seconds. If 00h then CCID default value is used. */
00197     unsigned char bTimeOut;
00198     /** Several parameters for the PIN format options (defined in § 6.1.11.4) */
00199     unsigned char bmFormatString4;
00200     /** Define the length of the PIN to present in the APDU command */
00201     unsigned char bmPINBlockString;
00202     /** Allows the length PIN insertion in the APDU command (defined in § 6.1.11.6) */
00203     unsigned char bmPinLengthFormat;
00204     /** Insertion position offset in byte for the current PIN */
00205     unsigned char bInsertionOffsetOld;
00206     /** Insertion position offset in byte for the new PIN */
00207     unsigned char bInsertionOffsetNew;
00208     /** XXYYh */
00209     /** XX: Minimum PIN size in digit */
00210     /** YY: Maximum PIN size in digit */
00211     unsigned char wPINMaxExtraDigit;
00212     /** 00h,01h,02h,03h */
00213     /** Indicates if a confirmation is requested before acceptance of a new PIN (meaning that the user has to enter this new PIN twice before it is accepted) */
00214     /** Indicates if the current PIN must be entered and set in the same APDU field of not. */
00215     unsigned char bConfirmPIN;
00216     /** The value is a bit wise OR operation. */
00217     /** 01h Max size reached */
00218     /** 02h Validation key pressed */
00219     /** 04h Timeout occurred */
00220     unsigned char bEntryValidationCondition;
00221     /** 00h,01h,02h,03h,or FFh */
00222     /** Number of messages to display for the PIN modify command. */
00223     unsigned char bNumberMessage;
00224     /** Language used to display the messages. The 16 bit */
00225     unsigned char wLangId;
00226     /** Message index in the Reader message table (should be 00h or 01h). */
00227     unsigned char bMsgIndex1;
00228     /** Message index in the Reader message table (should be 01h or 02h). */
00229     unsigned char bMsgIndex2;
00230     /** Message index in the Reader message table (should be 02h). */
00231     unsigned char bMsgIndex3;
00232     /** T=1 I-block prologue field to use. Significant only if protocol in use is T=1. */
00233     unsigned char bTeoPrologue[3];
00234     /** Byte array APDU to send to the ICC */
00235     unsigned char abPINApdu[255];
00236 }__attribute__ ((packed)) S_ccid_PIN_Modification;
00237 
00238 /** 
00239  * \typedef S_ccid_protocol_t0 
00240  * \brief Protocol Data Structure for Protocol T=0 (bProtocolNum=0, dwLength=00000005h) 
00241  */
00242 typedef struct _S_ccid_protocol_t0
00243 {
00244     /** B7-4 – FI – Index into the table 7 in ISO/IEC 7816-3:1997 selecting a */
00245     /** clock rate conversion factor */
00246     /** B3-0 – DI - Index into the table 8 in ISO/IEC 7816-3:1997 selecting a */
00247     /** baud rate conversion factor */
00248     unsigned char bmFindexDindex;
00249     /** For T=0 ,B0 – 0b, B7-2 – 000000b */
00250     /** B1 – Convention used (b1=0 for direct, b1=1 for inverse) */
00251     unsigned char bmTCCKST0;         /* 0 to 2 */
00252 
00253     /** Extra Guardtime between two characters. Add 0 to 254 etu to the normal */
00254     /** guardtime of 12etu. FFh is the same as 00h. */
00255     unsigned char bGuardTimeT0;      /* 0 to FF */
00256 
00257     /** WI for T=0 used to define WWT */
00258     unsigned char bWaitingIntegerT0; /* 0 to FF */
00259 
00260     /** ICC Clock Stop Support */
00261     /** 00 = Stopping the Clock is not allowed */
00262     /** 01 = Stop with Clock signal Low */
00263     /** 02 = Stop with Clock signal High */
00264     /** 03 = Stop with Clock either High or Low */
00265     unsigned char bClockStop;        /* 0 to 3 */
00266 
00267 } __attribute__ ((packed)) S_ccid_protocol_t0;
00268 
00269 
00270 /** 
00271  * \typedef S_ccid_protocol_t1
00272  * \brief Protocol Data Structure for Protocol T=1 (bProtocolNum=1, dwLength=00000007h) 
00273  */
00274 typedef struct _S_ccid_protocol_t1
00275 {
00276     /** B7-4 – FI – Index into the table 7 in ISO/IEC 7816-3:1997 selecting a */
00277     /** clock rate conversion factor */
00278     /** B3-0 – DI - Index into the table 8 in ISO/IEC 7816-3:1997 selecting a */
00279     /** baud rate conversion factor */
00280     unsigned char bmFindexDindex;
00281     /** For T=1, B7-2 – 000100b */
00282     /** B0 – Checksum type (b0=0 for LRC, b0=1 for CRC */
00283     /** B1 – Convention used (b1=0 for direct, b1=1 for inverse) */
00284     unsigned char bmTCCKST1;           /* 10h, 11h, 12h, 13h */
00285 
00286     /** Extra Guardtime (0 to 254 etu between two characters). */
00287     /** If value is FFh, then guardtime is reduced by 1. */
00288     unsigned char bGuardTimeT1;        /* 0 to FF */
00289 
00290     /** B7-4 = BWI */
00291     /** B3-0 = CWI */
00292     unsigned char bmWaitingIntegersT1; /* 0 to 9 */
00293 
00294     /** ICC Clock Stop Support */
00295     /** 00 = Stopping the Clock is not allowed */
00296     /** 01 = Stop with Clock signal Low */
00297     /** 02 = Stop with Clock signal High */
00298     /** 03 = Stop with Clock either High or Low */
00299     unsigned char bClockStop;          /* 0 to 3 */
00300 
00301     /** Size of negotiated IFSC */
00302     unsigned char bIFSC;               /* 0 to FE */
00303 
00304     /** Nad value used by CCID */
00305     unsigned char bNadValue;           /* 0 to FF */
00306 
00307 } __attribute__ ((packed)) S_ccid_protocol_t1;
00308 
00309 
00310 /** 
00311  * \typedef CCIDDescriptor
00312  * \brief Identifies the length of type of subordinate descriptors of a CCID device 
00313  * Table 5.1-1 Smart Card Device Class descriptors 
00314  */
00315 typedef struct _CCIDDescriptor
00316 {
00317    /** Size of this descriptor, in bytes. */
00318    unsigned char  bLength;
00319    /** Functional Descriptor type */
00320    unsigned char  bDescriptorType;
00321    /** Integrated Circuit(s) Cards Interface Devices (CCID) Specification */
00322    /** Release Number */
00323    unsigned short bcdCCID;
00324    /** Index of the highest available slot. An USB-ICC is regarded as a single */
00325    /** slot CCID. */
00326    unsigned char  bMaxSlotIndex;
00327    /** This value indicates what voltages the CCID can supply to its slots. */
00328    /** It is a bitwise OR operation performed on the following values: */
00329    /** - 01h 5.0V */
00330    /** - 02h 3.0V */
00331    /** - 04h 1.8V */
00332    /** Other bits are RFU. */
00333    unsigned char  bVoltageSupport;
00334    /** RRRR –Upper Word- is RFU = 0000h */
00335    /** PPPP –Lower Word- Encodes the supported protocol types. A ‘1’ in a given */
00336    /** bit position indicates support for the associated ISO protocol. */
00337    /** 0001h = Protocol T=0 */
00338    /** 0002h = Protocol T=1 */
00339    /** All other bits are reserved and must be set to zero. The field is */
00340    /** intended to correspond to the PCSC specification definitions. */
00341    unsigned long  dwProtocols;
00342    /** Default ICC clock frequency in KHz. This is an integer value. */
00343    unsigned long  dwDefaultClock;
00344    /** Maximum supported ICC clock frequency in KHz. This is an integer value. */
00345    unsigned long  dwMaximumClock;
00346    /** The number of clock frequencies that are supported by the CCID. If the */
00347    /** value is 00h, the supported clock frequencies are assumed to be the */
00348    /** default clock frequency defined by dwDefaultClock and the maximum clock */
00349    /** frequency defined by dwMaximumClock. */
00350    unsigned char  bNumClockSupported;
00351    /** Default ICC I/O data rate in bps. This is an integer value */
00352    unsigned long  dwDataRate;
00353    /** Maximum supported ICC I/O data rate in bps */
00354    unsigned long  dwMaxDataRate;
00355    /** The number of data rates that are supported by the CCID. */
00356    unsigned char  bNumDataRatesSupported;
00357    /** Indicates the maximum IFSD supported by CCID for protocol T=1. */
00358    unsigned long  dwMaxIFSD;
00359    /** - RRRR-Upper Word- is RFU = 0000h */
00360    /** - PPPP-Lower Word- encodes the supported protocol types. A ‘1’ in a given */
00361    /**   bit position indicates support for the associated protocol. */
00362    /**   0001h indicates support for the 2-wire protocol 1 */
00363    /**   0002h indicates support for the 3-wire protocol 1 */
00364    /**   0004h indicates support for the I2C protocol 1 */
00365    /** All other values are outside of this specification, and must be handled */
00366    /** by vendor-supplied drivers. */
00367    unsigned long  dwSynchProtocols;
00368    /** The value is a bitwise OR operation performed on the following values: */
00369    /** - 00000000h No special characteristics */
00370    /** - 00000001h Card accept mechanism 2 */
00371    /** - 00000002h Card ejection mechanism 2 */
00372    /** - 00000004h Card capture mechanism 2 */
00373    /** - 00000008h Card lock/unlock mechanism */
00374    unsigned long  dwMechanical;
00375    /** This value indicates what intelligent features the CCID has. */
00376    unsigned long  dwFeatures;
00377    /** For extended APDU level the value shall be between 261 + 10 (header) and */
00378    /** 65544 +10, otherwise the minimum value is the wMaxPacketSize of the */
00379    /** Bulk-OUT endpoint. */
00380    unsigned long  dwMaxCCIDMessageLength;
00381    /** Significant only for CCID that offers an APDU level for exchanges. */
00382    unsigned char  bClassGetResponse;
00383    /** Significant only for CCID that offers an extended APDU level for exchanges. */
00384    unsigned char  bClassEnvelope;
00385    /** Number of lines and characters for the LCD display used to send messages for PIN entry. */
00386    unsigned short wLcdLayout;
00387    /** This value indicates what PIN support features the CCID has. */
00388    unsigned char  bPINSupport;
00389    /** Maximum number of slots which can be simultaneously busy. */
00390    unsigned char  bMaxCCIDBusySlots;
00391 
00392 } __attribute__ ((packed)) CCIDDescriptor;
00393 
00394 #pragma pack()
00395 
00396 /*------------------------------------------------------------------------------ */
00397 
00398 /*         Exported functions */
00399 
00400 /*------------------------------------------------------------------------------ */
00401 
00402 
00403 extern unsigned char RDRtoPCHardwareError( unsigned char bSlot,
00404                                            unsigned char bSeq,
00405                                            unsigned char bHardwareErrorCode );
00406 
00407 #if !defined(NOAUTOCALLBACK)
00408 extern void USBDCallbacks_RequestReceived(const USBGenericRequest *pRequest);
00409 #endif
00410 extern void CCID_SmartCardRequest( void );
00411 extern void CCIDDriver_Initialize( void );
00412 extern unsigned char CCID_Read(void *pBuffer,
00413                                unsigned int dLength,
00414                                TransferCallback fCallback,
00415                                void *pArgument);
00416 extern unsigned char CCID_Write(void *pBuffer,
00417                                 unsigned int dLength,
00418                                 TransferCallback fCallback,
00419                                 void *pArgument);
00420 extern unsigned char CCID_Insertion( void );
00421 extern unsigned char CCID_Removal( void );
00422 
00423 /**@}*/
00424 
00425 #endif /*#ifndef CCID_DRIVER_H */
00426 
00427 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines