/[pcsclite]/trunk/Drivers/ccid/README
ViewVC logotype

Contents of /trunk/Drivers/ccid/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2020 - (show annotations) (download)
Sat Apr 22 15:31:05 2006 UTC (7 years ago) by rousseau
File size: 20608 byte(s)
release 1.0.1
1 USB CCID IFD Handler
2 ====================
3
4 This package provides the source code for a generic USB CCID
5 (Chip/Smart Card Interface Devices) driver. See [1] for the USB CCID
6 specifications from the USB working group.
7
8
9 Authors:
10 ========
11
12 - Ludovic Rousseau <ludovic.rousseau@free.fr>
13 - Carlos Prados for the PPS and ATR parsing code (taken from his
14 towitoto driver) in towitoko/ directory.
15 - Olaf Kirch for the T=1 TPDU code (from the OpenCT package) in openct/
16 directory. I (Ludovic Rousseau) greatly improved this code.
17
18
19 Supported CCID readers:
20 =======================
21
22 (in alphabetical order)
23 - ActivCard USB reader 3.0
24 - Advanced Card Systems ACR 38U-CCID [16]
25 old versions of this reader have a bug: the reader do timeout when a
26 special USB frame is sent from the reader. If the frame size if a
27 multiple of wMaxPacketSize the communication is stopped.
28 - Athena ASE IIIe USB V2 [29]
29 - Athena ASE IIIe KB USB [42]
30 - Cherry XX33 keyboard [?]
31 - Cherry XX44 keyboard (SmartBoard G83-6744) [18]
32 - Cherry SmartTerminal ST2000U [35]
33 - Cherry ST-1044U [27]
34 - Dell keyboard SK-3106 [?]
35 - Dell smart card reader keyboard [?]
36 - Eutron SIM Pocket Combo [25]
37 - Eutron CryptoIdentity [26]
38 - Gemplus GemPC 433 SL [2]
39 - Gemplus GemPC Card [41]
40 - Gemplus GemPC Key [3]
41 - Gemplus GemPC PinPad
42 - Gemplus GemPC Twin [4]
43 - Gemplus GemCore POS Pro
44 - Gemplus GemCore SIM Pro
45 - Kobil KAAN Base [19]
46 - Kobil KAAN Advanced [20]
47 - Kobil KAAN SIM III [21]
48 - Kobil mIDentity [22]
49 - OmniKey CardMan 3121 [5]
50 - SCM Micro SCR 331 [6]
51 You shall upgrade the firmware [17] using version 5.18 or later.
52 - SCM Micro SCR 331-DI [11]
53 You shall upgrade the firmware [17] using version 6.22 or later.
54 - SCM Micro SCR 335 [7]
55 The firmware of this reader can't be upgraded so be sure to buy a
56 recent model with firmware 5.14 or later
57 - SCM Micro SCR 355
58 - SCM Micro SCR 3310 [30]
59 - SCM Micro SCR 3311 [31]
60 - SCM Micro SPR 532 [9]
61 You shall contact Torsten Maykranz <tmaykranz@scmmicro.de> to get a
62 firmware upgrade.
63 - SmartEpad (v 2.0) [32]
64 The firmware gives a very strange description of the reader (like a
65 dwDefaultClock: 1024.000 MHz). So do not expect a perfect behavior.
66 - Verisign Secure Storage Token [24]
67 - Verisign Secure Token [?]
68
69
70 Should work but untested by me:
71 ===============================
72
73 I would like to get these readers to perform test and validation and
74 move them in the supported list above. If you are one of the
75 manufacturers, please, contact me.
76
77 - Axalto Reflex USB v3 [38]
78 - C3PO LTC32 [13]
79 - Gemplus GemPC Express
80 - OmniKey CardMan 3621 [43]
81 - OmniKey CardMan 3821 [37]
82 - OmniKey CardMan 5125 [33]
83 - OmniKey CardMan 6121 [36]
84 - SCM Micro SCR 331-DI NTTCom [23]
85 - SCM Micro SCR 3310-NTTCOM [28]
86 - SCM Micro SCR 3320 [32]
87 - SCM Micro SCR 333 [15]
88 - SCM Micro SDI 010 [39]
89 - SCM SCR 3340 ExpressCard54 [34]
90 - Silitek SK-3105 keyboard [12] or C3PO TLTC2USB [14]
91 - Winbond Electronics (for OEM only) [40]
92
93
94 Unsupported or partly supported CCID readers:
95 =============================================
96
97 - ActivCard USB reader 2.0 [10]
98 The reader do timeout when a special USB frame is sent from the
99 reader. If the frame size if a multiple of wMaxPacketSize the
100 communication is stopped.
101 - C3PO LTC31 [8]
102 The reader works fine with Linux kernel 2.4 but does not with Linux
103 kernel 2.6. The ioctl() syscall returns EINVAL (Invalid argument)
104 - RSA SecureID SID800 [24]
105 The USB layer is completely broken. The reader is sometimes not even
106 seen on the USB bus (same problem under Windows). Maybe newer
107 devices will work?
108
109
110 Supported operating systems:
111 ============================
112
113 - GNU/Linux (libusb 0.1.7)
114 - MacOS X/Darwin (libusb 0.1.8beta, CVS snapshot. See "Known problems")
115 to libusb)
116
117
118 Debug informations:
119 ===================
120
121 The driver uses the debug function provided by pcscd. So if pcscd sends
122 its debug to stderr (pcscd --foreground) then the CCID will also send
123 its debug to stderr. If pcscd sends its debug to syslog (by default)
124 then the CCID will also send its debug to syslog.
125
126 You can change the debug level using the Info.plist configuration file.
127 The Info.plist is installed, by default, in
128 /usr/local/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist
129
130 The debug level is set in the ifdLogLevel field. It is a binary OR
131 combinaison of 4 different levels.
132 - 1: critical: important error messages
133 - 2: info: informative messages like what reader was detected
134 - 4: comm: a dump of all the bytes exchanged between the host and the
135 reader
136 - 8: periodic: periodic info when pcscd test if a card is present (every
137 1/10 of a second)
138
139 By default the debug level is set to 3 (1 + 2) and correspond to the
140 critical and info levels.
141
142 You have to restart the driver so it read the configuration file again
143 and use the new debug level value. To restart the driver you just need
144 to unplug all your CCID readers so the the driver is unloaded and then
145 replug your readers. You can also restart pcscd.
146
147
148 Known problems:
149 ===============
150
151 MacOSX libusb
152 """""""""""""
153 There is a bug in libusb that crash the libusb library when you
154 unplug a reader and replug it in another USB socket. So if you
155 unplug a reader replug it in the same USB socket.
156
157 see http://sourceforge.net/tracker/index.php?func=detail&aid=886778&group_id=1674&atid=101674
158
159
160 Licence:
161 ========
162
163 This library is free software; you can redistribute it and/or modify it
164 under the terms of the GNU Lesser General Public License as published by
165 the Free Software Foundation; either version 2.1 of the License, or (at
166 your option) any later version.
167
168 This library is distributed in the hope that it will be useful, but
169 WITHOUT ANY WARRANTY; without even the implied warranty of
170 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
171 General Public License for more details.
172
173 You should have received a copy of the GNU Lesser General Public License
174 along with this library; if not, write to the Free Software Foundation,
175 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
176
177
178 History:
179 ========
180
181 1.0.1 - 22 April 2006, Ludovic Rousseau
182 - add support for Axalto Reflex USB v3, SCM Micro SDI 010, Winbond
183 Electronics W81E381 chipset, Gemplus GemPC Card, Athena ASE IIIe
184 KB USB, OmniKey CardMan 3621
185 - support Solaris (Solaris uses a different libusb)
186 - better documentation for ./configure arguments
187 - improve support of Cherry XX44 keyboard for PIN verify and change
188 (circumvent firmware bugs)
189 - do not use LTPBundleFindValueWithKey() from pcscd since this
190 function has been removed from pcscd API
191 - use -fvisibility=hidden is available to limit the number of
192 exported symbols
193
194
195 1.0.0 - 3 March 2006, Ludovic Rousseau
196 - add support for ActivCard USB Reader 3.0, Athena ASE IIIe USB V2,
197 SCM Micro SCR 355, SCR 3311, SCR 3320, SCR 3340 ExpressCard54,
198 Gemplus GemCore SIM Pro, GemCore POS Pro (serial and USB), GemPC
199 Express (ExpressCard/54 interface), SmartEpad (v 2.0), OmniKey
200 CardMan 5125
201 - greatly improve support of PIN PAD readers. We now support TPDU
202 readers with T=1 cards
203 - use l10n strings for the Gemplus GemPC PIN PAD (it has a screen).
204 Supported languages are: de, en, es, fr, it
205 - rename ACS ACR 38 in ACR 38U-CCID since the ACR 38 is a different
206 reader and is not CCID compatible
207 - allow to select the Power On voltage using Info.plist instead of
208 recompiling the source code
209 - correct bugs in the support of multi-slots readers
210 - if the card is faster than the reader (TA1=97 for example) we try
211 to use a not-so-bad speed (corresponding to TA1=96, 95 or 94)
212 instead of the default speed of TA1=11
213 - the src/parse tool do not use the driver anymore. No need to
214 update the Info.plist file first.
215 - some minor bugs removed
216
217
218 0.9.4 - 27 November 2005, Ludovic Rousseau
219 - add support for Eutron SIM Pocket Combo, Eutron CryptoIdentity,
220 Verisign Secure Token and VeriSign Secure Storage Token, GemPC
221 Card (PCMCIA), SCM SCR331-DI NTTCom, SCM Micro SCR 3310-NTTCom,
222 Cherry ST-1044U, Cherry SmartTerminal ST-2XXX
223 - add support of PC/SC v2 part 10 CM_IOCTL_GET_FEATURE_REQUEST add
224 support of FEATURE_VERIFY_PIN_DIRECT and FEATURE_MODIFY_PIN_DIRECT
225 remove support of IOCTL_SMARTCARD_VENDOR_VERIFY_PIN (now
226 obsoleted). A sample code is available in examples/scardcontrol.c
227 - we need pcsc-lite 1.2.9-beta9 since some structures used for PIN
228 pad readers are defined by pcsc-lite
229 - some (bogus) cards require an extra EGT but the ATR does not say
230 so. We try to detect the bogus cards and set TC1=2
231 - IFDHSetProtocolParameters(): only use a data rate supported by the
232 reader in the PPS negociation, otherwise we stay at the default
233 speed.
234 - calculate and store the read timeout according to the card ATR
235 instead of using a fixed value of 60 seconds
236 - increase the read timeout if the card sends and WTX request
237 - improve support of GemPC Twin and GemPC Card (serial protocol)
238 - reset the device on close only if DRIVER_OPTION_RESET_ON_CLOSE is
239 set. The problem was that a device reset also disconnects the
240 keyboard on a keyboard + reader device.
241 - use color logs
242 - some minor bugs removed
243
244
245 0.9.3 - 14 March 2005, Ludovic Rousseau
246 - change the licence from GNU GPL to GNU Lesser GPL (LGPL)
247 - add support for ACS ACR 38, Kobil KAAN Base, Kobil KAAN Advanced,
248 Kobil KAAN SIM III, Kobil KAAN mIDentity, SCM Micro SCR 331,
249 SCM Micro SCR 331-DI, SCM Micro SCR 335, SCM Micro SCR 3310,
250 SCM Micro SCR 532, Cherry XX44 readers
251 - improve communication speed with readers featuring "Automatic PPS
252 made by the CCID"
253 - switch the Cherry xx33 reader in ISO mode if power up in EMV mode
254 fails.
255 - add support of character level readers. Thanks to O2Micro for the
256 patch
257 - add support for the O2Micro OZ776S reader but the reader firmware
258 is still bogus
259 - check firmware version to avoid firmwares with bugs. You can still
260 use a bogus firmware by setting DRIVER_OPTION_USE_BOGUS_FIRMWARE
261 in Info.plist
262 - some minor bugs removed
263
264 0.9.2 - 15 August 2004, Ludovic Rousseau
265 - T=1 TPDU code:
266 . the work on T=1 TPDU code was possible thanks to Gemplus
267 validation team who helped me test, debug and bring the code to
268 an EMV validation level. Thanks to Jérôme, Jean-Yves, Xavier and
269 the Gemplus readers department
270 . error code was not checked correctly
271 . avoid a (nearly) infinite loop when resynch are needed.
272 . correctly initialise an internal value to allow more than one
273 reader to work
274 - multi-slots readers
275 . add support for multi-slots readers. The only one I have is a
276 SCM Micro SCR 331-DI with a contact and a contactless interface.
277 The contactless interface may or may not work for you since the
278 reader uses proprietary (undocumented) commands.
279 - GemPC Twin serial reader
280 . perform a command (get the reader firmware) to be sure a GemPC
281 Twin (serial or pcmcia) reader is connected
282 . use a dynamic timeout when reading the serial port.
283 The first timeout used when detecting the reader is 2 seconds to
284 not wait too long if no reader is connected. Later timeouts are
285 set to 1 minute to allow long time APDU.
286 - use `pkg-config libpcsclite --cflags` to locate the pcsc-lite
287 header files
288 - use `pkg-config --print-errors --atleast-version=1.2.9-beta5 libpcsclite`
289 to test the pcsc-lite version
290 - code improvements thanks to the splint tool (http://www.splint.org/)
291
292 0.9.1 - 1 July 2004, Ludovic Rousseau
293 - I forgot to define IFD_PARITY_ERROR in a .h file
294
295 0.9.0 - 1 July 2004, Ludovic Rousseau
296 - The T=1 TPDU automata from Carlos Prados' Towitoko driver is very
297 limited and do not support error management mechanisms.
298 I then used the T=1 TPDU automata from OpenCT (OpenSC project).
299 This automata is much more powerful but still lacks a lot of error
300 management code.
301 I then added all the needed code to reach the quality level
302 requested by the EMV standard.
303 - add support for new readers:
304 . Advanced Card Systems ACR 38
305 . Cherry XX33
306 . Dell keyboard SK-3106
307 . Dell smart card reader keyboard
308 . SCR 333
309 - add support of multi procotol cards (T=0 and T=1)
310 - the debug level is now dynamic and set in the Info.plist file (no
311 need to recompile the driver any more)
312 - add support for the libusb naming scheme: usb:%04x/%04x:libusb:%s
313 - INSTALL: add a "configuring the driver for the serial reader
314 (GemPC Twin)" part
315 - use `pkg-config libpcsclite --variable=usbdropdir` so you do not
316 have to use --enable-usbdropdir=DIR or --enable-ccidtwindir=DIR
317 even if pcscd does not use the default /usr/local/pcsc/drivers
318 - add support of IOCTL_SMARTCARD_VENDOR_IFD_EXCHANGE and
319 IOCTL_SMARTCARD_VENDOR_VERIFY_PIN in IFDHControl()
320 - read ifdDriverOptions from Info.plist to limit the use of
321 IOCTL_SMARTCARD_VENDOR_IFD_EXCHANGE (idea from Peter Williams)
322 - provide an example of use of SCardControl()
323 IOCTL_SMARTCARD_VENDOR_IFD_EXCHANGE and
324 IOCTL_SMARTCARD_VENDOR_VERIFY_PIN in example/
325 - add a --enable-pcsclite option (default to yes) so that the driver
326 can be compiled for a different framework (one needing
327 tokenparser.l like Solaris)
328 - Reset action is power off and power on, not just power on
329 - use the include files from pcsc-lite
330 - add a mechanism to allow power on at 1.8V, 3V and then 5V as
331 specified by ISO 7816. We still use 5V for now to avoid problems
332 with non ISO compliant cards
333
334 0.4.1 - 14 February 2004, Ludovic Rousseau
335 - distribute missing files readers/supported_readers.txt and
336 src/create_Info_plist.pl
337 'make install' failed because of this.
338
339 0.4.0 - 13 February 2004, Ludovic Rousseau
340 - support of T=1 with TPDU readers. A lot of the T=1 code comes from
341 Carlos Prados towitoko driver.
342 My code is GNU GPL, his code is GNU LGPL so the global driver is
343 GNU GPL
344 - PPS negotiation if the reader does not do it automatically
345 - add support for the Silitek SK-3105 keyboard. It's a USB device
346 with multiple interfaces
347 - use the create_Info_plist.pl script to generate the installed
348 Info.plist from an Info.plist template and a list of supported
349 readers. The Info.plist was too "complex" to maintain by hand
350 since it now contains 11 entries
351 - add support of IFDHCreateChannelByName to avoid wrong reader
352 enumeration. This is not complete if you have multiple _identical_
353 readers. You need to use a > 1.2.0 pcsc-lite version (not yet
354 released at that time)
355 - build but do not install the serial ccidtwin driver by default
356 since it is useless on computers without a serial port or without
357 this reader for example.
358 - read and write timeouts are not symmetric. write timout can be
359 shorter since the reader and card is not supposed to do anything
360 before receiving (write) a command
361 - do not try to find usb.h and other libusb files if
362 --disable-libusb is used. Needed if you only want to build the
363 serial driver. Thanks to Niki Waibel for the patch
364 - add a --enable-ccidtwindir argument to ./configure to specify the
365 serial GemPC Twin installation directory
366 - debug and code improvements and simplifications
367
368 0.3.2 - 4 November 2003, Ludovic Rousseau
369 - src/commands.c: correct a stupid bug that occurs with an APDU with
370 2 bytes response.
371 - Info.plist: add SPR 532 in list of supported readers
372 - parse.c: do not exit if the InterfaceClass is 0xFF (proprietary).
373 It is the case with old readers manufactured before the final
374 release of the CCID specs.
375 - move LTC31 reader from unsupported to supported reader list. It
376 was my f ault since in used odd INS byte in my test applet and odd
377 INS bytes are forbidden by ISO 7816-4 ch. 5.4.2 Instruction byte.
378 Thanks to Josep Moné s Teixidor for pointing the problem.
379 - src/commands.c: comment out the automatic GET RESPONSE part. I
380 don't think it should be in the driver. Maybe in pcscd instead?
381
382 0.3.1 - 23 September 2003, Ludovic Rouseau
383 - add --enable-multi-thread (enabled by default) for thread safe
384 support an APDU multiplexing. You will need pcsc-lite-1.2.0-rc3 or
385 above to use this feature.
386 - add --enable-libusb=PATH option is your libusb is not installed in
387 /usr or /usr/local
388 - honor DESTDIR in install rules (closes [ #300110 ]). Thanks to
389 Ville Skyttä for the patch.
390 - src/ccid.c: do not switch the GemPC Key and GemPC Twin in APDU
391 mode since it also swicth in EMV mode and may not work with non
392 EMV cards
393 - src/ccid_serial.c: complete reimplementation of the Twin serial
394 protocol using a finite state automata (code much simpler)
395
396 0.3.0 - 10 September 2003, Ludovic Rousseau
397 - support of GemPC Twin connected to a serial port. Thanks to Niki
398 W. Waibel for a working prototype.
399 - support of auto voltage at power up if the reader support it
400 instead of forcing a 5V in all cases.
401 - support of APDU mode instead of just TPDU if the reader support
402 it. Thanks to Jean-Luc Giraud for the idea and inspiration I got
403 from his "concurrent" driver.
404 - support of "time request" from the card.
405 - parse: new indentation for more readability of supported features.
406 - switch the GemPC Key and GemPC Twin in APDU mode since they
407 support it but do not announce it in the dwFeatures.
408 - new build process using autoconf/automake.
409
410 0.2.0 - 26 August 2003, Ludovic Rousseau
411 - Works under MacOS X
412 - Info.plist: use an <array></array> for the alias enumeration
413 - Makefile rework for *BSD and MacOS X
414
415 0.1.0 - 13 August 2003, Ludovic Rousseau
416 - First public release
417
418
419 References:
420 ===========
421
422 [1] http://www.usb.org/developers/devclass_docs/ccid_classspec_1_00a.pdf
423 [2] http://www.gemplus.com/products/gempc433/
424 [3] http://www.gemplus.com/products/gempckey/
425 [4] http://www.gemplus.com/products/gempctwin/
426 [5] http://www.omnikey.com/index.php?id=40
427 [6] http://www.scmmicro.com/security/SCR331.html
428 [7] http://www.scmmicro.com/security/SCR335.html
429 [8] http://www.c3po.es/ltc31.html
430 [9] http://www.scmmicro.com/security/SPR532.html
431 [10] http://www.activcard.com/products/usb_reader.html
432 [11] http://www.scmmicro.com/security/SCR331-DI.html
433 [12] http://www.silitek.com/prod/getProduct.do?xml_id=4_2&menu_id=4_2_8&cid=1_8_5
434 [13] http://www.c3po.es/ltc32.html
435 [14] http://www.c3po.es/tltc2usb.html
436 [15] http://www.scmmicro.com/security/SCR333.html
437 [16] http://www.acs.com.hk/Product_Readers.asp?productID=107&PCate=Products_PC_Linked_SmartCard_Readers
438 [17] http://www.scmmicro.com/support/pcs_product_drivers.html
439 [18] http://www.cherrycorp.com/english/advanced-line/advanced-line_smartboard_g83-6744.htm
440 [19] http://www.kobil.com/e/products/smartcard/kaan-base.php
441 [20] http://www.kobil.com/e/products/smartcard/kaan-advanced.php
442 [21] http://www.kobil.com/d/products/smartcard/kaansim3.php
443 [22] http://www.kobil.com/e/products/index.php?s=midentity
444 [23] http://www.ntt.com/jpki/SCR331DI.html
445 [24] http://www.verisign.co.uk/products-services/security-services/unified-authentication/usb-tokens/
446 [25] http://www.eutron.com/simpocket.asp
447 [26] http://www.cryptoidentity.eutron.com/eng/home.asp
448 [27] http://www.cherry.de/english/advanced-line/advanced_smartterminal_st-1044u.htm
449 [28] http://www.ntt.com/jpki/scr3310.html
450 [29] http://www.asedrive.com/product.asp?pid=1
451 [30] http://www.scmmicro.com/security/SCR3310.html
452 [31] http://scmmicro.com/security/SCR3311.html
453 [31] http://scmmicro.com/security/SCR3320.html
454 [32] http://www.smartepad.com.br/
455 [33] http://www.omnikey.com/index.php?id=121
456 [34] http://www.scmmicro.com/security/SCR3340.html
457 [35] http://www.cherry.de/deutsch/advanced-line/advanced_smart_terminal_st-2000u.htm
458 [36] http://www.omnikey.com/index.php?id=21
459 [37] http://www.omnikey.com/index.php?id=114
460 [38] http://www.reflexreaders.com/Products/reflex_usbnew.html
461 [39] http://www.scmmicro.com/security/SDI_010.html
462 [40] http://www.winbond.com.tw/E-WINBONDHTM/partner/b_2_e_4.htm
463 [41] http://www.gemplus.com/products/gempc_card/
464 [42] http://www.asedrive.com/product.asp?pid=2
465 [43] http://www.omnikey.com/index.php?id=50
466
467 $Id$
468
469 vim:ts=20

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

  ViewVC Help
Powered by ViewVC 1.1.5