1
Qemu CCID Device Documentation.
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
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:
20
Device Class: Smart Card
23
Integrated Circuit(s) Cards Interface Devices
27
Smartcard 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.
37
The cryptographic functions and access to the physical card is done via NSS.
44
apt-get install libnss3-dev
45
(not tested on ubuntu)
47
Configuring and building:
48
./configure --enable-smartcard && make
50
3. Using ccid-card-emulated with hardware
52
Assuming you have a working smartcard on the host with the current
53
user, using NSS, qemu acts as another NSS client using ccid-card-emulated:
55
qemu -usb -device usb-ccid -device ccid-card-emualated
57
4. Using ccid-card-emulated with certificates
59
You must create the certificates. This is a one time process. We use NSS
62
certutil -d /etc/pki/nssdb -x -t "CT,CT,CT" -S -s "CN=cert1" -n cert1
64
Note: you must have exactly three certificates.
66
Assuming the current user can access the certificates (use certutil -L to
67
verify), you can use the emulated card type with the certificates backend:
69
qemu -usb -device usb-ccid -device ccid-card-emulated,backend=certificates,cert1=cert1,cert2=cert2,cert3=cert3
71
5. Using ccid-card-passthru with client side hardware
73
on the host specify the ccid-card-passthru device with a suitable chardev:
75
qemu -chardev socket,server,host=0.0.0.0,port=2001,id=ccid,nowait -usb -device usb-ccid -device ccid-card-passthru,chardev=ccid
77
on the client run vscclient, built when you built the libcacard library:
78
libcacard/vscclient <qemu-host> 2001
80
6. Using ccid-card-passthru with client side certificates
82
Run qemu as per #5, and run vscclient as follows:
83
(Note: vscclient command line interface is in a state of change)
85
libcacard/vscclient -e "db=\"/etc/pki/nssdb\" use_hw=no soft=(,Test,CAC,,cert1,cert2,cert3)" <qemu-host> 2001
87
7. Passthrough protocol scenario
89
This is a typical interchange of messages when using the passthru card device.
90
usb-ccid is a usb device. It defaults to an unattached usb device on startup.
91
usb-ccid expects a chardev and expects the protocol defined in
92
cac_card/vscard_common.h to be passed over that.
93
The usb-ccid device can be in one of three modes:
95
* attached with no card
98
A typical interchange is: (the arrow shows who started each exchange, it can be client
99
originated or guest originated)
101
client event | vscclient | passthru | usb-ccid | guest event
102
----------------------------------------------------------------------------------------------
104
| VSC_ReaderAdd | | attach |
105
| | | | sees new usb device.
106
card inserted -> | | | |
107
| VSC_ATR | insert | insert | see new card
109
| VSC_APDU | VSC_APDU | | <- guest sends APDU
110
client<->physical | | | |
111
card APDU exchange| | | |
112
client response ->| VSC_APDU | VSC_APDU | | receive APDU response
114
[APDU<->APDU repeats several times]
116
card removed -> | | | |
117
| VSC_CardRemove | remove | remove | card removed
119
[(card insert, apdu's, card remove) repeat]
123
| VSC_ReaderRemove | | detach |
124
| | | | usb device removed.
129
ccid-card-passthru and vscclient use libcacard as the card emulator.
130
libcacard implements a completely virtual CAC (DoD standard for smart cards)
131
compliant card and uses NSS to actually retrive certificates and do any
132
encryption using the backend (real reader + card or file backed certificates).
134
For documentation of cac_card see README in libcacard subdirectory.
added
removed
docs/ccid.txt
