Contents of /trunk/Drivers/ccid/README

USB CCID IFD Handler
====================

  This package provides the source code for a generic USB CCID
(Chip/Smart Card Interface Devices) driver. See [1] for the USB CCID
specifications from the USB working group.


Authors:
========

- Ludovic Rousseau <ludovic.rousseau@free.fr>
- Carlos Prados for the TPDU T=1 code (taken from his towitoto driver)


Supported CCID readers:
=======================

(in alphabetical order)
- C3PO LTC31 [8]
- Gemplus GemPC 433 SL [2]
- Gemplus GemPC Key [3]
- Gemplus GemPC Twin [4]
- OmniKey CardMan 3121 [5]
- SCM Micro SCR 331 [6]
- SCM Micro SCR 335 [7]


Should work but untested by me:
===============================

I would like to get these readers to perform test and validation and
move them in the supported list above. If you are one of the
manufacturers, please, contact me.

- ActivCard USB reader 2.0 [10]
- C3PO LTC32 [13]
- SCM Micro SCR 331-DI [11]
- SCM Micro SCR 333 [15]
- SCM Micro SPR 532 [9]
- Silitek SK-3105 keyboard [12] or C3PO TLTC2USB [14]


Unsupported CCID readers:
=========================

None known.


Supported operating systems:
============================

- GNU/Linux (libusb 0.1.7)
- MacOS X/Darwin (libusb 0.1.8beta, CVS snapshot. See "Known problems")
  to libusb)


Debug informations:
===================

The driver uses the debug function provided by pcscd. So if pcscd sends
its debug to stdout (pcscd --foreground) then the CCID will also send
its debug to stdout. If pcscd sends its debug to syslog (by default)
then the CCID will also send its debug to syslog.

You can change the debug level using the Info.plist configuraion file.
The Info.plist is installed, by default, in
/usr/local/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist

The debug level is set in the ifdLogLevel field. It is a binary OR
combinaison of 4 different levels.
- 1: critical: important error messages
- 2: info:     informative messages like what reader was detected
- 4: periodic: periodic info when pcscd test if a card is present (every
               1/10 of a second)
- 8: comm:     a dump of all the bytes exchanged between the host and the
               reader

By default the debug level is set to 3 (1 + 2) and correspond to the
critical and info levels.

You have to restart the driver so it read the configuration file again
and use the new debug level value.  To restart the driver you just need
to unplug all your CCID readers so the the driver is unloaded and then
replug your readers. You can also restart pcscd.


Known problems:
===============

*BSD
    libusb
    """"""
      The libusb does not yet support USB interrupt endpoints. You will
      notice that the driver will stop working as soon as you insert a
      card in the reader.
      A new version of libusb should fix this bug.


Licence:
========

  This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

  This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

  You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA


History:
========

0.4.1 - 14 February 2004, Ludovic Rousseau
    - distribute missing files readers/supported_readers.txt and
      src/create_Info_plist.pl
      'make install' failed because of this.

0.4.0 - 13 February 2004, Ludovic Rousseau
    - support of T=1 with TPDU readers. A lot of the T=1 code comes from
      Carlos Prados towitoko driver.
      My code is GNU GPL, his code is GNU LGPL so the global driver is
      GNU GPL
    - PPS negotiation if the reader does not do it automatically
    - add support for the Silitek SK-3105 keyboard. It's a USB device
      with multiple interfaces
    - use the create_Info_plist.pl script to generate the installed
      Info.plist from an Info.plist template and a list of supported
      readers. The Info.plist was too "complex" to maintain by hand
      since it now contains 11 entries
    - add support of IFDHCreateChannelByName to avoid wrong reader
      enumeration. This is not complete if you have multiple _identical_
      readers. You need to use a > 1.2.0 pcsc-lite version (not yet
      released at that time)
    - build but do not install the serial ccidtwin driver by default
      since it is useless on computers without a serial port or without
      this reader for example.
    - read and write timeouts are not symmetric. write timout can be
      shorter since the reader and card is not supposed to do anything
      before receiving (write) a command
    - do not try to find usb.h and other libusb files if
      --disable-libusb is used. Needed if you only want to build the
      serial driver.  Thanks to Niki Waibel for the patch
    - add a --enable-ccidtwindir argument to ./configure to specify the
      serial GemPC Twin installation directory
    - debug and code improvements and simplifications

0.3.2 - 4 November 2003, Ludovic Rousseau
    - src/commands.c: correct a stupid bug that occurs with an APDU with
      2 bytes response.
    - Info.plist: add SPR 532 in list of supported readers
    - parse.c: do not exit if the InterfaceClass is 0xFF (proprietary).
      It is the case with old readers manufactured before the final
      release of the CCID specs.
    - move LTC31 reader from unsupported to supported reader list. It
      was my f ault since in used odd INS byte in my test applet and odd
      INS bytes are forbidden by ISO 7816-4 ch. 5.4.2 Instruction byte.
      Thanks to Josep Mon� s Teixidor for pointing the problem.
    - src/commands.c: comment out the automatic GET RESPONSE part. I
      don't think it should be in the driver. Maybe in pcscd instead?

0.3.1 - 23 September 2003, Ludovic Rouseau
    - add --enable-multi-thread (enabled by default) for thread safe
      support an APDU multiplexing. You will need pcsc-lite-1.2.0-rc3 or
      above to use this feature.
    - add --enable-libusb=PATH option is your libusb is not installed in
      /usr or /usr/local
    - honor DESTDIR in install rules (closes [ #300110 ]). Thanks to
      Ville Skytt� for the patch.
    - src/ccid.c: do not switch the GemPC Key and GemPC Twin in APDU
      mode since it also swicth in EMV mode and may not work with non
      EMV cards
    - src/ccid_serial.c: complete reimplementation of the Twin serial
      protocol using a finite state automata (code much simpler)

0.3.0 - 10 September 2003, Ludovic Rousseau
    - support of GemPC Twin connected to a serial port. Thanks to Niki
      W. Waibel for a working prototype.
    - support of auto voltage at power up if the reader support it
      instead of forcing a 5V in all cases.
    - support of APDU mode instead of just TPDU if the reader support
      it. Thanks to Jean-Luc Giraud for the idea and inspiration I got
      from his "concurrent" driver.
    - support of "time request" from the card.
    - parse: new indentation for more readability of supported features.
    - switch the GemPC Key and GemPC Twin in APDU mode since they
      support it but do not announce it in the dwFeatures.
    - new build process using autoconf/automake.

0.2.0 - 26 August 2003, Ludovic Rousseau
    - Works under MacOS X
    - Info.plist: use an <array></array> for the alias enumeration
    - Makefile rework for *BSD and MacOS X

0.1.0 - 13 August 2003, Ludovic Rousseau
    - First public release


Bibliography:
=============

[1] http://www.usb.org/developers/devclass_docs/ccid_classspec_1_00a.pdf
[2] http://www.gemplus.com/products/gempc433/
[3] http://www.gemplus.com/products/gempckey/
[4] http://www.gemplus.com/products/gempctwin/
[5] http://www.omnikey.com/en/produkt_details.php3?produkt=1&variante=47
[6] http://www.scmmicro.com/security/SCR331.html
[7] http://www.scmmicro.com/security/SCR335.html
[8] http://www.c3po.es/ltc31.html
[9] http://www.scmmicro.com/security/SPR532.html
[10] http://www.activcard.com/products/usb_reader.html
[11] http://www.scmmicro.com/security/SCR331-DI.html
[12] http://www.silitek.com/prod/getProduct.do?xml_id=4_2&menu_id=4_2_8&cid=1_8_5
[13] http://www.c3po.es/ltc32.html
[14] http://www.c3po.es/tltc2usb.html
[15] http://www.scmmicro.com/security/SCR333.html

$Id$

 vim:ts=20
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	697	- Carlos Prados for the TPDU T=1 code (taken from his towitoto driver)
14	rousseau	269
15
16			Supported CCID readers:
17			=======================
18
19	rousseau	273	(in alphabetical order)
20	rousseau	708	- C3PO LTC31 [8]
21	rousseau	273	- Gemplus GemPC 433 SL [2]
22			- Gemplus GemPC Key [3]
23			- Gemplus GemPC Twin [4]
24			- OmniKey CardMan 3121 [5]
25			- SCM Micro SCR 331 [6]
26			- SCM Micro SCR 335 [7]
27	rousseau	606
28
29			Should work but untested by me:
30			===============================
31
32			I would like to get these readers to perform test and validation and
33			move them in the supported list above. If you are one of the
34			manufacturers, please, contact me.
35
36	rousseau	708	- ActivCard USB reader 2.0 [10]
37	rousseau	709	- C3PO LTC32 [13]
38	rousseau	666	- SCM Micro SCR 331-DI [11]
39	rousseau	709	- SCM Micro SCR 333 [15]
40	rousseau	553	- SCM Micro SPR 532 [9]
41	rousseau	709	- Silitek SK-3105 keyboard [12] or C3PO TLTC2USB [14]
42	rousseau	269
43
44			Unsupported CCID readers:
45			=========================
46
47	rousseau	523	None known.
48	rousseau	269
49
50	rousseau	321	Supported operating systems:
51			============================
52
53			- GNU/Linux (libusb 0.1.7)
54			- MacOS X/Darwin (libusb 0.1.8beta, CVS snapshot. See "Known problems")
55			to libusb)
56
57
58	rousseau	862	Debug informations:
59			===================
60
61			The driver uses the debug function provided by pcscd. So if pcscd sends
62			its debug to stdout (pcscd --foreground) then the CCID will also send
63			its debug to stdout. If pcscd sends its debug to syslog (by default)
64			then the CCID will also send its debug to syslog.
65
66			You can change the debug level using the Info.plist configuraion file.
67			The Info.plist is installed, by default, in
68			/usr/local/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist
69
70			The debug level is set in the ifdLogLevel field. It is a binary OR
71			combinaison of 4 different levels.
72			- 1: critical: important error messages
73			- 2: info: informative messages like what reader was detected
74			- 4: periodic: periodic info when pcscd test if a card is present (every
75			1/10 of a second)
76			- 8: comm: a dump of all the bytes exchanged between the host and the
77			reader
78
79			By default the debug level is set to 3 (1 + 2) and correspond to the
80			critical and info levels.
81
82			You have to restart the driver so it read the configuration file again
83			and use the new debug level value. To restart the driver you just need
84			to unplug all your CCID readers so the the driver is unloaded and then
85			replug your readers. You can also restart pcscd.
86
87
88	rousseau	321	Known problems:
89			===============
90
91	rousseau	340	*BSD
92			libusb
93			""""""
94			The libusb does not yet support USB interrupt endpoints. You will
95			notice that the driver will stop working as soon as you insert a
96			card in the reader.
97			A new version of libusb should fix this bug.
98	rousseau	321
99	rousseau	340
100	rousseau	273	Licence:
101			========
102
103	rousseau	269	This program is free software; you can redistribute it and/or modify
104			it under the terms of the GNU General Public License as published by the
105			Free Software Foundation; either version 2 of the License, or (at your
106			option) any later version.
107
108			This program is distributed in the hope that it will be useful, but
109			WITHOUT ANY WARRANTY; without even the implied warranty of
110			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
111			General Public License for more details.
112
113			You should have received a copy of the GNU General Public License
114			along with this program; if not, write to the Free Software Foundation,
115			Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
116
117
118			History:
119			========
120
121	rousseau	703	0.4.1 - 14 February 2004, Ludovic Rousseau
122			- distribute missing files readers/supported_readers.txt and
123			src/create_Info_plist.pl
124			'make install' failed because of this.
125
126	rousseau	697	0.4.0 - 13 February 2004, Ludovic Rousseau
127			- support of T=1 with TPDU readers. A lot of the T=1 code comes from
128			Carlos Prados towitoko driver.
129			My code is GNU GPL, his code is GNU LGPL so the global driver is
130			GNU GPL
131			- PPS negotiation if the reader does not do it automatically
132			- add support for the Silitek SK-3105 keyboard. It's a USB device
133			with multiple interfaces
134			- use the create_Info_plist.pl script to generate the installed
135			Info.plist from an Info.plist template and a list of supported
136			readers. The Info.plist was too "complex" to maintain by hand
137			since it now contains 11 entries
138			- add support of IFDHCreateChannelByName to avoid wrong reader
139			enumeration. This is not complete if you have multiple _identical_
140			readers. You need to use a > 1.2.0 pcsc-lite version (not yet
141			released at that time)
142			- build but do not install the serial ccidtwin driver by default
143			since it is useless on computers without a serial port or without
144			this reader for example.
145			- read and write timeouts are not symmetric. write timout can be
146			shorter since the reader and card is not supposed to do anything
147			before receiving (write) a command
148			- do not try to find usb.h and other libusb files if
149			--disable-libusb is used. Needed if you only want to build the
150			serial driver. Thanks to Niki Waibel for the patch
151			- add a --enable-ccidtwindir argument to ./configure to specify the
152			serial GemPC Twin installation directory
153			- debug and code improvements and simplifications
154
155	rousseau	552	0.3.2 - 4 November 2003, Ludovic Rousseau
156			- src/commands.c: correct a stupid bug that occurs with an APDU with
157			2 bytes response.
158			- Info.plist: add SPR 532 in list of supported readers
159			- parse.c: do not exit if the InterfaceClass is 0xFF (proprietary).
160			It is the case with old readers manufactured before the final
161			release of the CCID specs.
162			- move LTC31 reader from unsupported to supported reader list. It
163			was my f ault since in used odd INS byte in my test applet and odd
164			INS bytes are forbidden by ISO 7816-4 ch. 5.4.2 Instruction byte.
165			Thanks to Josep Mon� s Teixidor for pointing the problem.
166			- src/commands.c: comment out the automatic GET RESPONSE part. I
167			don't think it should be in the driver. Maybe in pcscd instead?
168
169	rousseau	467	0.3.1 - 23 September 2003, Ludovic Rouseau
170			- add --enable-multi-thread (enabled by default) for thread safe
171			support an APDU multiplexing. You will need pcsc-lite-1.2.0-rc3 or
172			above to use this feature.
173			- add --enable-libusb=PATH option is your libusb is not installed in
174			/usr or /usr/local
175			- honor DESTDIR in install rules (closes [ #300110 ]). Thanks to
176			Ville Skytt� for the patch.
177			- src/ccid.c: do not switch the GemPC Key and GemPC Twin in APDU
178			mode since it also swicth in EMV mode and may not work with non
179			EMV cards
180			- src/ccid_serial.c: complete reimplementation of the Twin serial
181			protocol using a finite state automata (code much simpler)
182
183	rousseau	423	0.3.0 - 10 September 2003, Ludovic Rousseau
184			- support of GemPC Twin connected to a serial port. Thanks to Niki
185			W. Waibel for a working prototype.
186			- support of auto voltage at power up if the reader support it
187			instead of forcing a 5V in all cases.
188			- support of APDU mode instead of just TPDU if the reader support
189			it. Thanks to Jean-Luc Giraud for the idea and inspiration I got
190			from his "concurrent" driver.
191	rousseau	425	- support of "time request" from the card.
192	rousseau	423	- parse: new indentation for more readability of supported features.
193			- switch the GemPC Key and GemPC Twin in APDU mode since they
194			support it but do not announce it in the dwFeatures.
195			- new build process using autoconf/automake.
196
197	rousseau	342	0.2.0 - 26 August 2003, Ludovic Rousseau
198			- Works under MacOS X
199			- Info.plist: use an <array></array> for the alias enumeration
200			- Makefile rework for *BSD and MacOS X
201
202	rousseau	273	0.1.0 - 13 August 2003, Ludovic Rousseau
203			- First public release
204	rousseau	269
205
206	rousseau	425	Bibliography:
207			=============
208	rousseau	269
209			[1] http://www.usb.org/developers/devclass_docs/ccid_classspec_1_00a.pdf
210	rousseau	273	[2] http://www.gemplus.com/products/gempc433/
211			[3] http://www.gemplus.com/products/gempckey/
212	rousseau	269	[4] http://www.gemplus.com/products/gempctwin/
213	rousseau	273	[5] http://www.omnikey.com/en/produkt_details.php3?produkt=1&variante=47
214			[6] http://www.scmmicro.com/security/SCR331.html
215			[7] http://www.scmmicro.com/security/SCR335.html
216	rousseau	709	[8] http://www.c3po.es/ltc31.html
217	rousseau	553	[9] http://www.scmmicro.com/security/SPR532.html
218	rousseau	606	[10] http://www.activcard.com/products/usb_reader.html
219	rousseau	666	[11] http://www.scmmicro.com/security/SCR331-DI.html
220	rousseau	677	[12] http://www.silitek.com/prod/getProduct.do?xml_id=4_2&menu_id=4_2_8&cid=1_8_5
221	rousseau	709	[13] http://www.c3po.es/ltc32.html
222			[14] http://www.c3po.es/tltc2usb.html
223			[15] http://www.scmmicro.com/security/SCR333.html
224	rousseau	269
225			$Id$
226
227			vim:ts=20
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision