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

Contents of /trunk/Drivers/ccid/README

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.5