Christina Quast | db7b1ab | 2015-03-03 12:34:36 +0100 | [diff] [blame] | 1 | /* ---------------------------------------------------------------------------- |
| 2 | * ATMEL Microcontroller Software Support |
| 3 | * ---------------------------------------------------------------------------- |
| 4 | * Copyright (c) 2008, Atmel Corporation |
| 5 | * |
| 6 | * All rights reserved. |
| 7 | * |
| 8 | * Redistribution and use in source and binary forms, with or without |
| 9 | * modification, are permitted provided that the following conditions are met: |
| 10 | * |
| 11 | * - Redistributions of source code must retain the above copyright notice, |
| 12 | * this list of conditions and the disclaimer below. |
| 13 | * |
| 14 | * Atmel's name may not be used to endorse or promote products derived from |
| 15 | * this software without specific prior written permission. |
| 16 | * |
| 17 | * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR |
| 18 | * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF |
| 19 | * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE |
| 20 | * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, |
| 21 | * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 22 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, |
| 23 | * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
| 24 | * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
| 25 | * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, |
| 26 | * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 27 | * ---------------------------------------------------------------------------- |
| 28 | */ |
| 29 | |
| 30 | //------------------------------------------------------------------------------ |
| 31 | /// \unit |
| 32 | /// |
| 33 | /// !Purpose |
| 34 | /// |
| 35 | /// Definition of methods for using a CCID device driver. |
| 36 | /// |
| 37 | /// !Usage |
| 38 | /// |
| 39 | /// -# CCIDDriver_Initialize |
| 40 | /// -# CCID_Read |
| 41 | /// -# CCID_Write |
| 42 | /// -# CCID_SmartCardRequest |
| 43 | /// -# CCID_Insertion |
| 44 | /// -# CCID_Removal |
| 45 | /// -# RDRtoPCHardwareError |
| 46 | //------------------------------------------------------------------------------ |
| 47 | |
| 48 | #ifndef CCID_DRIVER_H |
| 49 | #define CCID_DRIVER_H |
| 50 | |
Christina Quast | 6038eeb | 2015-04-09 16:55:46 +0200 | [diff] [blame] | 51 | #include "USBD.h" |
Christina Quast | db7b1ab | 2015-03-03 12:34:36 +0100 | [diff] [blame] | 52 | |
| 53 | /// For reference, the absolute maximum block size |
| 54 | /// for a TPDU T=0 block is 260 bytes (5 bytes command; 255 bytes data), or |
| 55 | /// for a TPDU T=1 block is 259 bytes, or |
| 56 | /// for a short APDU T=1 block is 261 bytes, or |
| 57 | /// for an extended APDU T=1 block is 65544 bytes. |
| 58 | #define ABDATA_SIZE 260 |
| 59 | |
| 60 | /// define protocol T=0 |
| 61 | #define PROTOCOL_TO 0 |
| 62 | /// define protocol T=1 |
| 63 | #define PROTOCOL_T1 1 |
| 64 | |
| 65 | /// define for dwFeatures see Table 5.1-1 Smart Card Device Class Descriptors |
| 66 | /// No special characteristics |
| 67 | #define CCID_FEATURES_NADA 0x00000000 |
| 68 | /// Automatic parameter configuration based on ATR data |
| 69 | #define CCID_FEATURES_AUTO_PCONF 0x00000002 |
| 70 | /// Automatic activation of ICC on inserting |
| 71 | #define CCID_FEATURES_AUTO_ACTIV 0x00000004 |
| 72 | /// Automatic ICC voltage selection |
| 73 | #define CCID_FEATURES_AUTO_VOLT 0x00000008 |
| 74 | /// Automatic ICC clock frequency change according to active parameters provided |
| 75 | /// by the Host or self determined |
| 76 | #define CCID_FEATURES_AUTO_CLOCK 0x00000010 |
| 77 | /// Automatic baud rate change according to active parameters provided by the |
| 78 | /// Host or self determined |
| 79 | #define CCID_FEATURES_AUTO_BAUD 0x00000020 |
| 80 | /// Automatic parameters negotiation made by the CCID (use of warm or cold |
| 81 | /// resets or PPS according to a manufacturer proprietary algorithm to select |
| 82 | /// the communication parameters with the ICC) |
| 83 | #define CCID_FEATURES_AUTO_PNEGO 0x00000040 |
| 84 | /// Automatic PPS made by the CCID according to the active parameters |
| 85 | #define CCID_FEATURES_AUTO_PPS 0x00000080 |
| 86 | /// CCID can set ICC in clock stop mode |
| 87 | #define CCID_FEATURES_ICCSTOP 0x00000100 |
| 88 | /// NAD value other than 00 accepted (T=1 protocol in use) |
| 89 | #define CCID_FEATURES_NAD 0x00000200 |
| 90 | /// Automatic IFSD exchange as first exchange (T=1 protocol in use) |
| 91 | #define CCID_FEATURES_AUTO_IFSD 0x00000400 |
| 92 | /// TPDU level exchanges with CCID |
| 93 | #define CCID_FEATURES_EXC_TPDU 0x00010000 |
| 94 | /// Short APDU level exchange with CCID |
| 95 | #define CCID_FEATURES_EXC_SAPDU 0x00020000 |
| 96 | /// Short and Extended APDU level exchange with CCID |
| 97 | #define CCID_FEATURES_EXC_APDU 0x00040000 |
| 98 | /// USB Wake up signaling supported on card insertion and removal |
| 99 | #define CCID_FEATURES_WAKEUP 0x00100000 |
| 100 | |
| 101 | //------------------------------------------------------------------------------ |
| 102 | // Types |
| 103 | //------------------------------------------------------------------------------ |
| 104 | |
| 105 | /// Bulk CCID Message header structure |
| 106 | typedef struct |
| 107 | { |
| 108 | unsigned char bMessageType; |
| 109 | /// Message-specific data length |
| 110 | unsigned long wLength; |
| 111 | /// Identifies the slot number for this command |
| 112 | unsigned char bSlot; |
| 113 | /// Sequence number for command. |
| 114 | unsigned char bSeq; |
| 115 | /// Slot status register |
| 116 | unsigned char bStatus; |
| 117 | /// Slot error |
| 118 | unsigned char bError; |
| 119 | /// specific register |
| 120 | unsigned char bSpecific; |
| 121 | /// Data block sent to the CCID. |
| 122 | unsigned char abData[ABDATA_SIZE]; |
| 123 | unsigned char bSizeToSend; |
| 124 | } __attribute__ ((packed)) S_ccid_bulk_in_header; |
| 125 | |
| 126 | /// 6.1 Bulk Transfers |
| 127 | typedef struct |
| 128 | { |
| 129 | unsigned char bMessageType; |
| 130 | /// Message-specific data length |
| 131 | unsigned long wLength; |
| 132 | /// Identifies the slot number for this command |
| 133 | unsigned char bSlot; |
| 134 | /// Sequence number for command. |
| 135 | unsigned char bSeq; |
| 136 | /// specific register |
| 137 | unsigned char bSpecific_0; |
| 138 | unsigned char bSpecific_1; |
| 139 | unsigned char bSpecific_2; |
| 140 | /// Application Protocol Data Unit |
| 141 | unsigned char APDU[ABDATA_SIZE]; |
| 142 | } __attribute__ ((packed)) S_ccid_bulk_out_header; |
| 143 | |
| 144 | |
| 145 | /// 6.1.11.2 PIN Verification Data Structure |
| 146 | typedef struct |
| 147 | { |
| 148 | /// Number of seconds. |
| 149 | unsigned char bTimerOut; |
| 150 | /// Several parameters for the PIN format options |
| 151 | unsigned char bmFormatString; |
| 152 | /// Define the length of the PIN to present in the APDU command |
| 153 | unsigned char bmPINBlockString; |
| 154 | /// Allows the length PIN insertion in the APDU command |
| 155 | unsigned char bmPINLengthFormat; |
| 156 | /// Minimum PIN size in digit and Maximum PIN size in digit |
| 157 | unsigned char wPINMaxExtraDigit; |
| 158 | /// The value is a bit wise OR operation. |
| 159 | unsigned char bEntryValidationCondition; |
| 160 | /// Number of messages to display for the PIN modify command |
| 161 | unsigned char bNumberMessage; |
| 162 | /// Language used to display the messages. |
| 163 | unsigned char wLangId; |
| 164 | /// Message index in the Reader message table |
| 165 | unsigned char bMsgIndex; |
| 166 | /// T=1 I-block prologue field to use |
| 167 | unsigned char bTeoPrologue[3]; |
| 168 | /// APDU to send to the ICC |
| 169 | unsigned char abPINApdu[255]; |
| 170 | }__attribute__ ((packed)) S_ccid_PIN_Verification; |
| 171 | |
| 172 | |
| 173 | /// 6.1.11.7 PIN Modification Data Structure |
| 174 | typedef struct |
| 175 | { |
| 176 | /// Number of seconds. If 00h then CCID default value is used. |
| 177 | unsigned char bTimeOut; |
| 178 | /// Several parameters for the PIN format options (defined in § 6.1.11.4) |
| 179 | unsigned char bmFormatString4; |
| 180 | /// Define the length of the PIN to present in the APDU command |
| 181 | unsigned char bmPINBlockString; |
| 182 | /// Allows the length PIN insertion in the APDU command (defined in § 6.1.11.6) |
| 183 | unsigned char bmPinLengthFormat; |
| 184 | /// Insertion position offset in byte for the current PIN |
| 185 | unsigned char bInsertionOffsetOld; |
| 186 | /// Insertion position offset in byte for the new PIN |
| 187 | unsigned char bInsertionOffsetNew; |
| 188 | /// XXYYh |
| 189 | /// XX: Minimum PIN size in digit |
| 190 | /// YY: Maximum PIN size in digit |
| 191 | unsigned char wPINMaxExtraDigit; |
| 192 | /// 00h,01h,02h,03h |
| 193 | /// 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) |
| 194 | /// Indicates if the current PIN must be entered and set in the same APDU field of not. |
| 195 | unsigned char bConfirmPIN; |
| 196 | /// The value is a bit wise OR operation. |
| 197 | /// 01h Max size reached |
| 198 | /// 02h Validation key pressed |
| 199 | /// 04h Timeout occurred |
| 200 | unsigned char bEntryValidationCondition; |
| 201 | /// 00h,01h,02h,03h,or FFh |
| 202 | /// Number of messages to display for the PIN modify command. |
| 203 | unsigned char bNumberMessage; |
| 204 | /// Language used to display the messages. The 16 bit |
| 205 | unsigned char wLangId; |
| 206 | /// Message index in the Reader message table (should be 00h or 01h). |
| 207 | unsigned char bMsgIndex1; |
| 208 | /// Message index in the Reader message table (should be 01h or 02h). |
| 209 | unsigned char bMsgIndex2; |
| 210 | /// Message index in the Reader message table (should be 02h). |
| 211 | unsigned char bMsgIndex3; |
| 212 | /// T=1 I-block prologue field to use. Significant only if protocol in use is T=1. |
| 213 | unsigned char bTeoPrologue[3]; |
| 214 | /// Byte array APDU to send to the ICC |
| 215 | unsigned char abPINApdu[255]; |
| 216 | }__attribute__ ((packed)) S_ccid_PIN_Modification; |
| 217 | |
| 218 | /// Protocol Data Structure for Protocol T=0 (bProtocolNum=0, dwLength=00000005h) |
| 219 | typedef struct |
| 220 | { |
| 221 | /// B7-4 FI Index into the table 7 in ISO/IEC 7816-3:1997 selecting a |
| 222 | /// clock rate conversion factor |
| 223 | /// B3-0 DI - Index into the table 8 in ISO/IEC 7816-3:1997 selecting a |
| 224 | /// baud rate conversion factor |
| 225 | unsigned char bmFindexDindex; |
| 226 | /// For T=0 ,B0 0b, B7-2 000000b |
| 227 | /// B1 Convention used (b1=0 for direct, b1=1 for inverse) |
| 228 | unsigned char bmTCCKST0; // 0 to 2 |
| 229 | /// Extra Guardtime between two characters. Add 0 to 254 etu to the normal |
| 230 | /// guardtime of 12etu. FFh is the same as 00h. |
| 231 | unsigned char bGuardTimeT0; // 0 to FF |
| 232 | /// WI for T=0 used to define WWT |
| 233 | unsigned char bWaitingIntegerT0; // 0 to FF |
| 234 | /// ICC Clock Stop Support |
| 235 | /// 00 = Stopping the Clock is not allowed |
| 236 | /// 01 = Stop with Clock signal Low |
| 237 | /// 02 = Stop with Clock signal High |
| 238 | /// 03 = Stop with Clock either High or Low |
| 239 | unsigned char bClockStop; // 0 to 3 |
| 240 | } __attribute__ ((packed)) S_ccid_protocol_t0; |
| 241 | |
| 242 | |
| 243 | /// Protocol Data Structure for Protocol T=1 (bProtocolNum=1, dwLength=00000007h) |
| 244 | typedef struct |
| 245 | { |
| 246 | /// B7-4 FI Index into the table 7 in ISO/IEC 7816-3:1997 selecting a |
| 247 | /// clock rate conversion factor |
| 248 | /// B3-0 DI - Index into the table 8 in ISO/IEC 7816-3:1997 selecting a |
| 249 | /// baud rate conversion factor |
| 250 | unsigned char bmFindexDindex; |
| 251 | /// For T=1, B7-2 000100b |
| 252 | /// B0 Checksum type (b0=0 for LRC, b0=1 for CRC |
| 253 | /// B1 Convention used (b1=0 for direct, b1=1 for inverse) |
| 254 | unsigned char bmTCCKST1; // 10h, 11h, 12h, 13h |
| 255 | /// Extra Guardtime (0 to 254 etu between two characters). |
| 256 | /// If value is FFh, then guardtime is reduced by 1. |
| 257 | unsigned char bGuardTimeT1; // 0 to FF |
| 258 | /// B7-4 = BWI |
| 259 | /// B3-0 = CWI |
| 260 | unsigned char bmWaitingIntegersT1; // 0 to 9 |
| 261 | /// ICC Clock Stop Support |
| 262 | /// 00 = Stopping the Clock is not allowed |
| 263 | /// 01 = Stop with Clock signal Low |
| 264 | /// 02 = Stop with Clock signal High |
| 265 | /// 03 = Stop with Clock either High or Low |
| 266 | unsigned char bClockStop; // 0 to 3 |
| 267 | /// Size of negotiated IFSC |
| 268 | unsigned char bIFSC; // 0 to FE |
| 269 | /// Nad value used by CCID |
| 270 | unsigned char bNadValue; // 0 to FF |
| 271 | } __attribute__ ((packed)) S_ccid_protocol_t1; |
| 272 | |
| 273 | |
| 274 | /// Identifies the length of type of subordinate descriptors of a CCID device |
| 275 | /// Table 5.1-1 Smart Card Device Class descriptors |
| 276 | typedef struct |
| 277 | { |
| 278 | /// Size of this descriptor, in bytes. |
| 279 | unsigned char bLength; |
| 280 | /// Functional Descriptor type |
| 281 | unsigned char bDescriptorType; |
| 282 | /// Integrated Circuit(s) Cards Interface Devices (CCID) Specification |
| 283 | /// Release Number |
| 284 | unsigned short bcdCCID; |
| 285 | /// Index of the highest available slot. An USB-ICC is regarded as a single |
| 286 | /// slot CCID. |
| 287 | unsigned char bMaxSlotIndex; |
| 288 | /// This value indicates what voltages the CCID can supply to its slots. |
| 289 | /// It is a bitwise OR operation performed on the following values: |
| 290 | /// - 01h 5.0V |
| 291 | /// - 02h 3.0V |
| 292 | /// - 04h 1.8V |
| 293 | /// Other bits are RFU. |
| 294 | unsigned char bVoltageSupport; |
| 295 | /// RRRR Upper Word- is RFU = 0000h |
| 296 | /// PPPP Lower Word- Encodes the supported protocol types. A 1 in a given |
| 297 | /// bit position indicates support for the associated ISO protocol. |
| 298 | /// 0001h = Protocol T=0 |
| 299 | /// 0002h = Protocol T=1 |
| 300 | /// All other bits are reserved and must be set to zero. The field is |
| 301 | /// intended to correspond to the PCSC specification definitions. |
| 302 | unsigned long dwProtocols; |
| 303 | /// Default ICC clock frequency in KHz. This is an integer value. |
| 304 | unsigned long dwDefaultClock; |
| 305 | /// Maximum supported ICC clock frequency in KHz. This is an integer value. |
| 306 | unsigned long dwMaximumClock; |
| 307 | /// The number of clock frequencies that are supported by the CCID. If the |
| 308 | /// value is 00h, the supported clock frequencies are assumed to be the |
| 309 | /// default clock frequency defined by dwDefaultClock and the maximum clock |
| 310 | /// frequency defined by dwMaximumClock. |
| 311 | unsigned char bNumClockSupported; |
| 312 | /// Default ICC I/O data rate in bps. This is an integer value |
| 313 | unsigned long dwDataRate; |
| 314 | /// Maximum supported ICC I/O data rate in bps |
| 315 | unsigned long dwMaxDataRate; |
| 316 | /// The number of data rates that are supported by the CCID. |
| 317 | unsigned char bNumDataRatesSupported; |
| 318 | /// Indicates the maximum IFSD supported by CCID for protocol T=1. |
| 319 | unsigned long dwMaxIFSD; |
| 320 | /// - RRRR-Upper Word- is RFU = 0000h |
| 321 | /// - PPPP-Lower Word- encodes the supported protocol types. A 1 in a given |
| 322 | /// bit position indicates support for the associated protocol. |
| 323 | /// 0001h indicates support for the 2-wire protocol 1 |
| 324 | /// 0002h indicates support for the 3-wire protocol 1 |
| 325 | /// 0004h indicates support for the I2C protocol 1 |
| 326 | /// All other values are outside of this specification, and must be handled |
| 327 | /// by vendor-supplied drivers. |
| 328 | unsigned long dwSynchProtocols; |
| 329 | /// The value is a bitwise OR operation performed on the following values: |
| 330 | /// - 00000000h No special characteristics |
| 331 | /// - 00000001h Card accept mechanism 2 |
| 332 | /// - 00000002h Card ejection mechanism 2 |
| 333 | /// - 00000004h Card capture mechanism 2 |
| 334 | /// - 00000008h Card lock/unlock mechanism |
| 335 | unsigned long dwMechanical; |
| 336 | /// This value indicates what intelligent features the CCID has. |
| 337 | unsigned long dwFeatures; |
| 338 | /// For extended APDU level the value shall be between 261 + 10 (header) and |
| 339 | /// 65544 +10, otherwise the minimum value is the wMaxPacketSize of the |
| 340 | /// Bulk-OUT endpoint. |
| 341 | unsigned long dwMaxCCIDMessageLength; |
| 342 | /// Significant only for CCID that offers an APDU level for exchanges. |
| 343 | unsigned char bClassGetResponse; |
| 344 | /// Significant only for CCID that offers an extended APDU level for exchanges. |
| 345 | unsigned char bClassEnvelope; |
| 346 | /// Number of lines and characters for the LCD display used to send messages for PIN entry. |
| 347 | unsigned short wLcdLayout; |
| 348 | /// This value indicates what PIN support features the CCID has. |
| 349 | unsigned char bPINSupport; |
| 350 | /// Maximum number of slots which can be simultaneously busy. |
| 351 | unsigned char bMaxCCIDBusySlots; |
| 352 | |
| 353 | } __attribute__ ((packed)) CCIDDescriptor; |
| 354 | |
| 355 | //------------------------------------------------------------------------------ |
| 356 | // Exported functions |
| 357 | //------------------------------------------------------------------------------ |
| 358 | |
| 359 | extern unsigned char RDRtoPCHardwareError( unsigned char bSlot, |
| 360 | unsigned char bSeq, |
| 361 | unsigned char bHardwareErrorCode ); |
| 362 | |
| 363 | /* |
| 364 | #if !defined(NOAUTOCALLBACK) |
| 365 | extern void USBDCallbacks_RequestReceived(const USBGenericRequest *request); |
| 366 | #endif |
| 367 | */ |
| 368 | extern void CCID_SmartCardRequest( void ); |
| 369 | extern void CCIDDriver_Initialize( void ); |
| 370 | extern unsigned char CCID_Read(void *pBuffer, |
| 371 | unsigned int dLength, |
| 372 | TransferCallback fCallback, |
| 373 | void *pArgument); |
| 374 | extern unsigned char CCID_Write(void *pBuffer, |
| 375 | unsigned int dLength, |
| 376 | TransferCallback fCallback, |
| 377 | void *pArgument); |
| 378 | extern unsigned char CCID_Insertion( void ); |
| 379 | extern unsigned char CCID_Removal( void ); |
| 380 | |
| 381 | #endif //#ifndef CCID_DRIVER_H |
| 382 | |