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)


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

All platforms
    readers enumeration
    """""""""""""""""""
      You may have wrong reader identification if you connect two or
      more reader at the exact same time.

      The daemon pcscd and the CCID driver do not list connected readers
      in the same order. The driver has no way to know which reader has
      been detected as a new reader by pcscd.
      
      So if you plug two readers at the same time (for example if you
      start pcscd with two readers connected or if you plug a USB hub
      with two readers on the hub) you may have this (with two readers
      foo and bar):
      - pcscd scans the USB bus and finds a new CCID reader foo and
        calls the driver
      - the CCID driver scan the USB bus and finds a new different
        reader bar
      - pcscd continues scanning the USB bus and finds the second reader
        bar and calls the driver
      - the CCID driver scan the USB bus and finds an unused reader foo.

        Now the reader foo will be called bar by pcscd and bar will be
        called foo. This may not be a problem if the two readers have
        the same name. But it is strange to insert a card in the
        physical reader foo and see pcscd detect the card insertion in
        the reader he calls bar.
        
        The solution is to use IFDHCreateChannelByName() instead of
        IFDHCreateChannel() and specify the USB device to use. But pcscd
        does not implement IFDHCreateChannelByName() yet. Maybe in the
        future.
        
        Another solution is to plug readers one after the other and not
        at the same time.

*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			Known problems:
59			===============
60
61	rousseau	326	All platforms
62	rousseau	321	readers enumeration
63	rousseau	326	"""""""""""""""""""
64			You may have wrong reader identification if you connect two or
65			more reader at the exact same time.
66	rousseau	321
67	rousseau	326	The daemon pcscd and the CCID driver do not list connected readers
68			in the same order. The driver has no way to know which reader has
69			been detected as a new reader by pcscd.
70
71			So if you plug two readers at the same time (for example if you
72			start pcscd with two readers connected or if you plug a USB hub
73			with two readers on the hub) you may have this (with two readers
74			foo and bar):
75			- pcscd scans the USB bus and finds a new CCID reader foo and
76			calls the driver
77			- the CCID driver scan the USB bus and finds a new different
78			reader bar
79	rousseau	321	- pcscd continues scanning the USB bus and finds the second reader
80			bar and calls the driver
81			- the CCID driver scan the USB bus and finds an unused reader foo.
82
83	rousseau	326	Now the reader foo will be called bar by pcscd and bar will be
84			called foo. This may not be a problem if the two readers have
85			the same name. But it is strange to insert a card in the
86			physical reader foo and see pcscd detect the card insertion in
87			the reader he calls bar.
88
89			The solution is to use IFDHCreateChannelByName() instead of
90			IFDHCreateChannel() and specify the USB device to use. But pcscd
91			does not implement IFDHCreateChannelByName() yet. Maybe in the
92			future.
93
94			Another solution is to plug readers one after the other and not
95			at the same time.
96
97	rousseau	340	*BSD
98			libusb
99			""""""
100			The libusb does not yet support USB interrupt endpoints. You will
101			notice that the driver will stop working as soon as you insert a
102			card in the reader.
103			A new version of libusb should fix this bug.
104	rousseau	321
105	rousseau	340
106	rousseau	273	Licence:
107			========
108
109	rousseau	269	This program is free software; you can redistribute it and/or modify
110			it under the terms of the GNU General Public License as published by the
111			Free Software Foundation; either version 2 of the License, or (at your
112			option) any later version.
113
114			This program is distributed in the hope that it will be useful, but
115			WITHOUT ANY WARRANTY; without even the implied warranty of
116			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
117			General Public License for more details.
118
119			You should have received a copy of the GNU General Public License
120			along with this program; if not, write to the Free Software Foundation,
121			Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
122
123
124			History:
125			========
126
127	rousseau	703	0.4.1 - 14 February 2004, Ludovic Rousseau
128			- distribute missing files readers/supported_readers.txt and
129			src/create_Info_plist.pl
130			'make install' failed because of this.
131
132	rousseau	697	0.4.0 - 13 February 2004, Ludovic Rousseau
133			- support of T=1 with TPDU readers. A lot of the T=1 code comes from
134			Carlos Prados towitoko driver.
135			My code is GNU GPL, his code is GNU LGPL so the global driver is
136			GNU GPL
137			- PPS negotiation if the reader does not do it automatically
138			- add support for the Silitek SK-3105 keyboard. It's a USB device
139			with multiple interfaces
140			- use the create_Info_plist.pl script to generate the installed
141			Info.plist from an Info.plist template and a list of supported
142			readers. The Info.plist was too "complex" to maintain by hand
143			since it now contains 11 entries
144			- add support of IFDHCreateChannelByName to avoid wrong reader
145			enumeration. This is not complete if you have multiple _identical_
146			readers. You need to use a > 1.2.0 pcsc-lite version (not yet
147			released at that time)
148			- build but do not install the serial ccidtwin driver by default
149			since it is useless on computers without a serial port or without
150			this reader for example.
151			- read and write timeouts are not symmetric. write timout can be
152			shorter since the reader and card is not supposed to do anything
153			before receiving (write) a command
154			- do not try to find usb.h and other libusb files if
155			--disable-libusb is used. Needed if you only want to build the
156			serial driver. Thanks to Niki Waibel for the patch
157			- add a --enable-ccidtwindir argument to ./configure to specify the
158			serial GemPC Twin installation directory
159			- debug and code improvements and simplifications
160
161	rousseau	552	0.3.2 - 4 November 2003, Ludovic Rousseau
162			- src/commands.c: correct a stupid bug that occurs with an APDU with
163			2 bytes response.
164			- Info.plist: add SPR 532 in list of supported readers
165			- parse.c: do not exit if the InterfaceClass is 0xFF (proprietary).
166			It is the case with old readers manufactured before the final
167			release of the CCID specs.
168			- move LTC31 reader from unsupported to supported reader list. It
169			was my f ault since in used odd INS byte in my test applet and odd
170			INS bytes are forbidden by ISO 7816-4 ch. 5.4.2 Instruction byte.
171			Thanks to Josep Mon� s Teixidor for pointing the problem.
172			- src/commands.c: comment out the automatic GET RESPONSE part. I
173			don't think it should be in the driver. Maybe in pcscd instead?
174
175	rousseau	467	0.3.1 - 23 September 2003, Ludovic Rouseau
176			- add --enable-multi-thread (enabled by default) for thread safe
177			support an APDU multiplexing. You will need pcsc-lite-1.2.0-rc3 or
178			above to use this feature.
179			- add --enable-libusb=PATH option is your libusb is not installed in
180			/usr or /usr/local
181			- honor DESTDIR in install rules (closes [ #300110 ]). Thanks to
182			Ville Skytt� for the patch.
183			- src/ccid.c: do not switch the GemPC Key and GemPC Twin in APDU
184			mode since it also swicth in EMV mode and may not work with non
185			EMV cards
186			- src/ccid_serial.c: complete reimplementation of the Twin serial
187			protocol using a finite state automata (code much simpler)
188
189	rousseau	423	0.3.0 - 10 September 2003, Ludovic Rousseau
190			- support of GemPC Twin connected to a serial port. Thanks to Niki
191			W. Waibel for a working prototype.
192			- support of auto voltage at power up if the reader support it
193			instead of forcing a 5V in all cases.
194			- support of APDU mode instead of just TPDU if the reader support
195			it. Thanks to Jean-Luc Giraud for the idea and inspiration I got
196			from his "concurrent" driver.
197	rousseau	425	- support of "time request" from the card.
198	rousseau	423	- parse: new indentation for more readability of supported features.
199			- switch the GemPC Key and GemPC Twin in APDU mode since they
200			support it but do not announce it in the dwFeatures.
201			- new build process using autoconf/automake.
202
203	rousseau	342	0.2.0 - 26 August 2003, Ludovic Rousseau
204			- Works under MacOS X
205			- Info.plist: use an <array></array> for the alias enumeration
206			- Makefile rework for *BSD and MacOS X
207
208	rousseau	273	0.1.0 - 13 August 2003, Ludovic Rousseau
209			- First public release
210	rousseau	269
211
212	rousseau	425	Bibliography:
213			=============
214	rousseau	269
215			[1] http://www.usb.org/developers/devclass_docs/ccid_classspec_1_00a.pdf
216	rousseau	273	[2] http://www.gemplus.com/products/gempc433/
217			[3] http://www.gemplus.com/products/gempckey/
218	rousseau	269	[4] http://www.gemplus.com/products/gempctwin/
219	rousseau	273	[5] http://www.omnikey.com/en/produkt_details.php3?produkt=1&variante=47
220			[6] http://www.scmmicro.com/security/SCR331.html
221			[7] http://www.scmmicro.com/security/SCR335.html
222	rousseau	709	[8] http://www.c3po.es/ltc31.html
223	rousseau	553	[9] http://www.scmmicro.com/security/SPR532.html
224	rousseau	606	[10] http://www.activcard.com/products/usb_reader.html
225	rousseau	666	[11] http://www.scmmicro.com/security/SCR331-DI.html
226	rousseau	677	[12] http://www.silitek.com/prod/getProduct.do?xml_id=4_2&menu_id=4_2_8&cid=1_8_5
227	rousseau	709	[13] http://www.c3po.es/ltc32.html
228			[14] http://www.c3po.es/tltc2usb.html
229			[15] http://www.scmmicro.com/security/SCR333.html
230	rousseau	269
231			$Id$
232
233			vim:ts=20
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision