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.


Author:
=======

- Ludovic Rousseau <ludovic.rousseau@free.fr>


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

(in alphabetical order)
- Gemplus GemPC 433 SL [2]
- Gemplus GemPC Key [3]
- Gemplus GemPC Twin [4]
- LTC31 from C3PO [8]
- 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.

- SCM Micro SCR 331-DI [11]
- SCM Micro SPR 532 [9]
- ActivCard USB reader 2.0 [10]
- Silitek SK-3105 keyboard


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
    T=1 and TPDU
    """"""""""""
      I do not yet included support of T=1 cards when the reader is in
      TPDU mode.
      If you have a T=1 card I recommand you to use a reader working in
      APDU mode. T=1 and TPDU will be supported in a future version of
      the driver.

    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.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/pcsc.htm
[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

$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			Author:
10			=======
11
12			- Ludovic Rousseau <ludovic.rousseau@free.fr>
13
14
15			Supported CCID readers:
16			=======================
17
18	rousseau	273	(in alphabetical order)
19			- Gemplus GemPC 433 SL [2]
20			- Gemplus GemPC Key [3]
21			- Gemplus GemPC Twin [4]
22	rousseau	523	- LTC31 from C3PO [8]
23	rousseau	273	- OmniKey CardMan 3121 [5]
24			- SCM Micro SCR 331 [6]
25			- SCM Micro SCR 335 [7]
26	rousseau	606
27
28			Should work but untested by me:
29			===============================
30
31			I would like to get these readers to perform test and validation and
32			move them in the supported list above. If you are one of the
33			manufacturers, please, contact me.
34
35	rousseau	666	- SCM Micro SCR 331-DI [11]
36	rousseau	553	- SCM Micro SPR 532 [9]
37	rousseau	606	- ActivCard USB reader 2.0 [10]
38	rousseau	654	- Silitek SK-3105 keyboard
39	rousseau	269
40
41			Unsupported CCID readers:
42			=========================
43
44	rousseau	523	None known.
45	rousseau	269
46
47	rousseau	321	Supported operating systems:
48			============================
49
50			- GNU/Linux (libusb 0.1.7)
51			- MacOS X/Darwin (libusb 0.1.8beta, CVS snapshot. See "Known problems")
52			to libusb)
53
54
55			Known problems:
56			===============
57
58	rousseau	326	All platforms
59	rousseau	465	T=1 and TPDU
60			""""""""""""
61			I do not yet included support of T=1 cards when the reader is in
62			TPDU mode.
63			If you have a T=1 card I recommand you to use a reader working in
64			APDU mode. T=1 and TPDU will be supported in a future version of
65			the driver.
66
67	rousseau	321	readers enumeration
68	rousseau	326	"""""""""""""""""""
69			You may have wrong reader identification if you connect two or
70			more reader at the exact same time.
71	rousseau	321
72	rousseau	326	The daemon pcscd and the CCID driver do not list connected readers
73			in the same order. The driver has no way to know which reader has
74			been detected as a new reader by pcscd.
75
76			So if you plug two readers at the same time (for example if you
77			start pcscd with two readers connected or if you plug a USB hub
78			with two readers on the hub) you may have this (with two readers
79			foo and bar):
80			- pcscd scans the USB bus and finds a new CCID reader foo and
81			calls the driver
82			- the CCID driver scan the USB bus and finds a new different
83			reader bar
84	rousseau	321	- pcscd continues scanning the USB bus and finds the second reader
85			bar and calls the driver
86			- the CCID driver scan the USB bus and finds an unused reader foo.
87
88	rousseau	326	Now the reader foo will be called bar by pcscd and bar will be
89			called foo. This may not be a problem if the two readers have
90			the same name. But it is strange to insert a card in the
91			physical reader foo and see pcscd detect the card insertion in
92			the reader he calls bar.
93
94			The solution is to use IFDHCreateChannelByName() instead of
95			IFDHCreateChannel() and specify the USB device to use. But pcscd
96			does not implement IFDHCreateChannelByName() yet. Maybe in the
97			future.
98
99			Another solution is to plug readers one after the other and not
100			at the same time.
101
102	rousseau	340	*BSD
103			libusb
104			""""""
105			The libusb does not yet support USB interrupt endpoints. You will
106			notice that the driver will stop working as soon as you insert a
107			card in the reader.
108			A new version of libusb should fix this bug.
109	rousseau	321
110	rousseau	340
111	rousseau	273	Licence:
112			========
113
114	rousseau	269	This program is free software; you can redistribute it and/or modify
115			it under the terms of the GNU General Public License as published by the
116			Free Software Foundation; either version 2 of the License, or (at your
117			option) any later version.
118
119			This program is distributed in the hope that it will be useful, but
120			WITHOUT ANY WARRANTY; without even the implied warranty of
121			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
122			General Public License for more details.
123
124			You should have received a copy of the GNU General Public License
125			along with this program; if not, write to the Free Software Foundation,
126			Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
127
128
129			History:
130			========
131
132	rousseau	552	0.3.2 - 4 November 2003, Ludovic Rousseau
133			- src/commands.c: correct a stupid bug that occurs with an APDU with
134			2 bytes response.
135			- Info.plist: add SPR 532 in list of supported readers
136			- parse.c: do not exit if the InterfaceClass is 0xFF (proprietary).
137			It is the case with old readers manufactured before the final
138			release of the CCID specs.
139			- move LTC31 reader from unsupported to supported reader list. It
140			was my f ault since in used odd INS byte in my test applet and odd
141			INS bytes are forbidden by ISO 7816-4 ch. 5.4.2 Instruction byte.
142			Thanks to Josep Mon� s Teixidor for pointing the problem.
143			- src/commands.c: comment out the automatic GET RESPONSE part. I
144			don't think it should be in the driver. Maybe in pcscd instead?
145
146	rousseau	467	0.3.1 - 23 September 2003, Ludovic Rouseau
147			- add --enable-multi-thread (enabled by default) for thread safe
148			support an APDU multiplexing. You will need pcsc-lite-1.2.0-rc3 or
149			above to use this feature.
150			- add --enable-libusb=PATH option is your libusb is not installed in
151			/usr or /usr/local
152			- honor DESTDIR in install rules (closes [ #300110 ]). Thanks to
153			Ville Skytt� for the patch.
154			- src/ccid.c: do not switch the GemPC Key and GemPC Twin in APDU
155			mode since it also swicth in EMV mode and may not work with non
156			EMV cards
157			- src/ccid_serial.c: complete reimplementation of the Twin serial
158			protocol using a finite state automata (code much simpler)
159
160	rousseau	423	0.3.0 - 10 September 2003, Ludovic Rousseau
161			- support of GemPC Twin connected to a serial port. Thanks to Niki
162			W. Waibel for a working prototype.
163			- support of auto voltage at power up if the reader support it
164			instead of forcing a 5V in all cases.
165			- support of APDU mode instead of just TPDU if the reader support
166			it. Thanks to Jean-Luc Giraud for the idea and inspiration I got
167			from his "concurrent" driver.
168	rousseau	425	- support of "time request" from the card.
169	rousseau	423	- parse: new indentation for more readability of supported features.
170			- switch the GemPC Key and GemPC Twin in APDU mode since they
171			support it but do not announce it in the dwFeatures.
172			- new build process using autoconf/automake.
173
174	rousseau	342	0.2.0 - 26 August 2003, Ludovic Rousseau
175			- Works under MacOS X
176			- Info.plist: use an <array></array> for the alias enumeration
177			- Makefile rework for *BSD and MacOS X
178
179	rousseau	273	0.1.0 - 13 August 2003, Ludovic Rousseau
180			- First public release
181	rousseau	269
182
183	rousseau	425	Bibliography:
184			=============
185	rousseau	269
186			[1] http://www.usb.org/developers/devclass_docs/ccid_classspec_1_00a.pdf
187	rousseau	273	[2] http://www.gemplus.com/products/gempc433/
188			[3] http://www.gemplus.com/products/gempckey/
189	rousseau	269	[4] http://www.gemplus.com/products/gempctwin/
190	rousseau	273	[5] http://www.omnikey.com/en/produkt_details.php3?produkt=1&variante=47
191			[6] http://www.scmmicro.com/security/SCR331.html
192			[7] http://www.scmmicro.com/security/SCR335.html
193	rousseau	423	[8] http://www.c3po.es/pcsc.htm
194	rousseau	553	[9] http://www.scmmicro.com/security/SPR532.html
195	rousseau	606	[10] http://www.activcard.com/products/usb_reader.html
196	rousseau	666	[11] http://www.scmmicro.com/security/SCR331-DI.html
197	rousseau	269
198			$Id$
199
200			vim:ts=20
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision