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

Contents of /trunk/Drivers/ccid/README

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.5