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]
- OmniKey CardMan 3121 [5]
- SCM Micro SCR 331 [6]
- SCM Micro SCR 335 [7]


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

- LTC31 from C3PO [8]
  Communication errors between the card and the reader. Some cards can't
  send an ATR.  I have the exact same symptoms with the Windows driver
  provided by C3PO.


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.

MacOS X/Darwin
    hotplug
    """""""
      Due to libusb work in progress the driver may crash on a reader
      insertion after a few insert/remove actions.
      So if your reader is always connected you should not have
      problems.
      A new version of libusb should fix this bug

*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.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

$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			- OmniKey CardMan 3121 [5]
23			- SCM Micro SCR 331 [6]
24			- SCM Micro SCR 335 [7]
25	rousseau	269
26
27			Unsupported CCID readers:
28			=========================
29
30	rousseau	423	- LTC31 from C3PO [8]
31			Communication errors between the card and the reader. Some cards can't
32			send an ATR. I have the exact same symptoms with the Windows driver
33			provided by C3PO.
34	rousseau	269
35
36	rousseau	321	Supported operating systems:
37			============================
38
39			- GNU/Linux (libusb 0.1.7)
40			- MacOS X/Darwin (libusb 0.1.8beta, CVS snapshot. See "Known problems")
41			to libusb)
42
43
44			Known problems:
45			===============
46
47	rousseau	326	All platforms
48	rousseau	321	readers enumeration
49	rousseau	326	"""""""""""""""""""
50			You may have wrong reader identification if you connect two or
51			more reader at the exact same time.
52	rousseau	321
53	rousseau	326	The daemon pcscd and the CCID driver do not list connected readers
54			in the same order. The driver has no way to know which reader has
55			been detected as a new reader by pcscd.
56
57			So if you plug two readers at the same time (for example if you
58			start pcscd with two readers connected or if you plug a USB hub
59			with two readers on the hub) you may have this (with two readers
60			foo and bar):
61			- pcscd scans the USB bus and finds a new CCID reader foo and
62			calls the driver
63			- the CCID driver scan the USB bus and finds a new different
64			reader bar
65	rousseau	321	- pcscd continues scanning the USB bus and finds the second reader
66			bar and calls the driver
67			- the CCID driver scan the USB bus and finds an unused reader foo.
68
69	rousseau	326	Now the reader foo will be called bar by pcscd and bar will be
70			called foo. This may not be a problem if the two readers have
71			the same name. But it is strange to insert a card in the
72			physical reader foo and see pcscd detect the card insertion in
73			the reader he calls bar.
74
75			The solution is to use IFDHCreateChannelByName() instead of
76			IFDHCreateChannel() and specify the USB device to use. But pcscd
77			does not implement IFDHCreateChannelByName() yet. Maybe in the
78			future.
79
80			Another solution is to plug readers one after the other and not
81			at the same time.
82
83			MacOS X/Darwin
84	rousseau	321	hotplug
85	rousseau	326	"""""""
86	rousseau	321	Due to libusb work in progress the driver may crash on a reader
87			insertion after a few insert/remove actions.
88			So if your reader is always connected you should not have
89			problems.
90	rousseau	423	A new version of libusb should fix this bug
91	rousseau	321
92	rousseau	340	*BSD
93			libusb
94			""""""
95			The libusb does not yet support USB interrupt endpoints. You will
96			notice that the driver will stop working as soon as you insert a
97			card in the reader.
98			A new version of libusb should fix this bug.
99	rousseau	321
100	rousseau	340
101	rousseau	273	Licence:
102			========
103
104	rousseau	269	This program is free software; you can redistribute it and/or modify
105			it under the terms of the GNU General Public License as published by the
106			Free Software Foundation; either version 2 of the License, or (at your
107			option) any later version.
108
109			This program is distributed in the hope that it will be useful, but
110			WITHOUT ANY WARRANTY; without even the implied warranty of
111			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
112			General Public License for more details.
113
114			You should have received a copy of the GNU General Public License
115			along with this program; if not, write to the Free Software Foundation,
116			Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
117
118
119			History:
120			========
121
122	rousseau	423	0.3.0 - 10 September 2003, Ludovic Rousseau
123			- support of GemPC Twin connected to a serial port. Thanks to Niki
124			W. Waibel for a working prototype.
125			- support of auto voltage at power up if the reader support it
126			instead of forcing a 5V in all cases.
127			- support of APDU mode instead of just TPDU if the reader support
128			it. Thanks to Jean-Luc Giraud for the idea and inspiration I got
129			from his "concurrent" driver.
130	rousseau	425	- support of "time request" from the card.
131	rousseau	423	- parse: new indentation for more readability of supported features.
132			- switch the GemPC Key and GemPC Twin in APDU mode since they
133			support it but do not announce it in the dwFeatures.
134			- new build process using autoconf/automake.
135
136	rousseau	342	0.2.0 - 26 August 2003, Ludovic Rousseau
137			- Works under MacOS X
138			- Info.plist: use an <array></array> for the alias enumeration
139			- Makefile rework for *BSD and MacOS X
140
141	rousseau	273	0.1.0 - 13 August 2003, Ludovic Rousseau
142			- First public release
143	rousseau	269
144
145	rousseau	425	Bibliography:
146			=============
147	rousseau	269
148			[1] http://www.usb.org/developers/devclass_docs/ccid_classspec_1_00a.pdf
149	rousseau	273	[2] http://www.gemplus.com/products/gempc433/
150			[3] http://www.gemplus.com/products/gempckey/
151	rousseau	269	[4] http://www.gemplus.com/products/gempctwin/
152	rousseau	273	[5] http://www.omnikey.com/en/produkt_details.php3?produkt=1&variante=47
153			[6] http://www.scmmicro.com/security/SCR331.html
154			[7] http://www.scmmicro.com/security/SCR335.html
155	rousseau	423	[8] http://www.c3po.es/pcsc.htm
156	rousseau	269
157			$Id$
158
159			vim:ts=20
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision