00001 /* ---------------------------------------------------------------------------- */ 00002 /* Atmel Microcontroller Software Support */ 00003 /* SAM Software Package License */ 00004 /* ---------------------------------------------------------------------------- */ 00005 /* Copyright (c) 2015, Atmel Corporation */ 00006 /* */ 00007 /* All rights reserved. */ 00008 /* */ 00009 /* Redistribution and use in source and binary forms, with or without */ 00010 /* modification, are permitted provided that the following condition is met: */ 00011 /* */ 00012 /* - Redistributions of source code must retain the above copyright notice, */ 00013 /* this list of conditions and the disclaimer below. */ 00014 /* */ 00015 /* Atmel's name may not be used to endorse or promote products derived from */ 00016 /* this software without specific prior written permission. */ 00017 /* */ 00018 /* DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR */ 00019 /* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */ 00020 /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE */ 00021 /* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, */ 00022 /* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */ 00023 /* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, */ 00024 /* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF */ 00025 /* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING */ 00026 /* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */ 00027 /* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ 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