hw/arm/virt: pass VirtMachineState instead of VirtGuestInfo
[qemu.git] / docs / ccid.txt
1 QEMU CCID Device Documentation.
2
3 Contents
4 1. USB CCID device
5 2. Building
6 3. Using ccid-card-emulated with hardware
7 4. Using ccid-card-emulated with certificates
8 5. Using ccid-card-passthru with client side hardware
9 6. Using ccid-card-passthru with client side certificates
10 7. Passthrough protocol scenario
11 8. libcacard
12
13 1. USB CCID device
14
15 The USB CCID device is a USB device implementing the CCID specification, which
16 lets one connect smart card readers that implement the same spec. For more
17 information see the specification:
18
19  Universal Serial Bus
20  Device Class: Smart Card
21  CCID
22  Specification for
23  Integrated Circuit(s) Cards Interface Devices
24  Revision 1.1
25  April 22rd, 2005
26
27 Smartcards are used for authentication, single sign on, decryption in
28 public/private schemes and digital signatures. A smartcard reader on the client
29 cannot be used on a guest with simple usb passthrough since it will then not be
30 available on the client, possibly locking the computer when it is "removed". On
31 the other hand this device can let you use the smartcard on both the client and
32 the guest machine. It is also possible to have a completely virtual smart card
33 reader and smart card (i.e. not backed by a physical device) using this device.
34
35 2. Building
36
37 The cryptographic functions and access to the physical card is done via NSS.
38
39 Installing NSS:
40
41 In redhat/fedora:
42     yum install nss-devel
43 In ubuntu/debian:
44     apt-get install libnss3-dev
45     (not tested on ubuntu)
46
47 Configuring and building:
48     ./configure --enable-smartcard && make
49
50
51 3. Using ccid-card-emulated with hardware
52
53 Assuming you have a working smartcard on the host with the current
54 user, using NSS, qemu acts as another NSS client using ccid-card-emulated:
55
56     qemu -usb -device usb-ccid -device ccid-card-emulated
57
58
59 4. Using ccid-card-emulated with certificates stored in files
60
61 You must create the CA and card certificates. This is a one time process.
62 We use NSS certificates:
63
64     mkdir fake-smartcard
65     cd fake-smartcard
66     certutil -N -d sql:$PWD
67     certutil -S -d sql:$PWD -s "CN=Fake Smart Card CA" -x -t TC,TC,TC -n fake-smartcard-ca
68     certutil -S -d sql:$PWD -t ,, -s "CN=John Doe" -n id-cert -c fake-smartcard-ca
69     certutil -S -d sql:$PWD -t ,, -s "CN=John Doe (signing)" --nsCertType smime -n signing-cert -c fake-smartcard-ca
70     certutil -S -d sql:$PWD -t ,, -s "CN=John Doe (encryption)" --nsCertType sslClient -n encryption-cert -c fake-smartcard-ca
71
72 Note: you must have exactly three certificates.
73
74 You can use the emulated card type with the certificates backend:
75
76     qemu -usb -device usb-ccid -device ccid-card-emulated,backend=certificates,db=sql:$PWD,cert1=id-cert,cert2=signing-cert,cert3=encryption-cert
77
78 To use the certificates in the guest, export the CA certificate:
79
80     certutil -L -r -d sql:$PWD -o fake-smartcard-ca.cer -n fake-smartcard-ca
81
82 and import it in the guest:
83
84     certutil -A -d /etc/pki/nssdb -i fake-smartcard-ca.cer -t TC,TC,TC -n fake-smartcard-ca
85
86 In a Linux guest you can then use the CoolKey PKCS #11 module to access
87 the card:
88
89     certutil -d /etc/pki/nssdb -L -h all
90
91 It will prompt you for the PIN (which is the password you assigned to the
92 certificate database early on), and then show you all three certificates
93 together with the manually imported CA cert:
94
95     Certificate Nickname                        Trust Attributes
96     fake-smartcard-ca                           CT,C,C
97     John Doe:CAC ID Certificate                 u,u,u
98     John Doe:CAC Email Signature Certificate    u,u,u
99     John Doe:CAC Email Encryption Certificate   u,u,u
100
101 If this does not happen, CoolKey is not installed or not registered with
102 NSS.  Registration can be done from Firefox or the command line:
103
104     modutil -dbdir /etc/pki/nssdb -add "CAC Module" -libfile /usr/lib64/pkcs11/libcoolkeypk11.so
105     modutil -dbdir /etc/pki/nssdb -list
106
107
108 5. Using ccid-card-passthru with client side hardware
109
110 on the host specify the ccid-card-passthru device with a suitable chardev:
111
112     qemu -chardev socket,server,host=0.0.0.0,port=2001,id=ccid,nowait -usb -device usb-ccid -device ccid-card-passthru,chardev=ccid
113
114 on the client run vscclient, built when you built QEMU:
115
116     vscclient <qemu-host> 2001
117
118
119 6. Using ccid-card-passthru with client side certificates
120
121 This case is not particularly useful, but you can use it to debug
122 your setup if #4 works but #5 does not.
123
124 Follow instructions as per #4, except run QEMU and vscclient as follows:
125 Run qemu as per #5, and run vscclient from the "fake-smartcard"
126 directory as follows:
127
128     qemu -chardev socket,server,host=0.0.0.0,port=2001,id=ccid,nowait -usb -device usb-ccid -device ccid-card-passthru,chardev=ccid
129     vscclient -e "db=\"sql:$PWD\" use_hw=no soft=(,Test,CAC,,id-cert,signing-cert,encryption-cert)" <qemu-host> 2001
130
131
132 7. Passthrough protocol scenario
133
134 This is a typical interchange of messages when using the passthru card device.
135 usb-ccid is a usb device. It defaults to an unattached usb device on startup.
136 usb-ccid expects a chardev and expects the protocol defined in
137 cac_card/vscard_common.h to be passed over that.
138 The usb-ccid device can be in one of three modes:
139  * detached
140  * attached with no card
141  * attached with card
142
143 A typical interchange is: (the arrow shows who started each exchange, it can be client
144 originated or guest originated)
145
146 client event      |      vscclient           |    passthru    |     usb-ccid  |  guest event
147 ----------------------------------------------------------------------------------------------
148                   |      VSC_Init            |                |               |
149                   |      VSC_ReaderAdd       |                |     attach    |
150                   |                          |                |               |  sees new usb device.
151 card inserted ->  |                          |                |               |
152                   |      VSC_ATR             |   insert       |     insert    |  see new card
153                   |                          |                |               |
154                   |      VSC_APDU            |   VSC_APDU     |               | <- guest sends APDU
155 client<->physical |                          |                |               |
156 card APDU exchange|                          |                |               |
157 client response ->|      VSC_APDU            |   VSC_APDU     |               |  receive APDU response
158                                                     ...
159                                     [APDU<->APDU repeats several times]
160                                                     ...
161 card removed  ->  |                          |                |               |
162                   |      VSC_CardRemove      |   remove       |    remove     |   card removed
163                                                     ...
164                                     [(card insert, apdu's, card remove) repeat]
165                                                     ...
166 kill/quit         |                          |                |               |
167   vscclient       |                          |                |               |
168                   |      VSC_ReaderRemove    |                |    detach     |
169                   |                          |                |               |   usb device removed.
170
171
172 8. libcacard
173
174 Both ccid-card-emulated and vscclient use libcacard as the card emulator.
175 libcacard implements a completely virtual CAC (DoD standard for smart
176 cards) compliant card and uses NSS to retrieve certificates and do
177 any encryption.  The backend can then be a real reader and card, or
178 certificates stored in files.
179
180 For documentation of the library see docs/libcacard.txt.
181