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

Diff of /trunk/Drivers/ccid/README

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

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

Legend:
Removed from v.273  
changed lines
  Added in v.1945

  ViewVC Help
Powered by ViewVC 1.1.5