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

Contents of /trunk/Drivers/ccid/README

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.5