root / docs / ccid.txt @ 2542bfd5
History | View | Annotate | Download (5.7 kB)
| 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 |
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. |
| 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 |
3. Using ccid-card-emulated with hardware |
| 51 |
|
| 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: |
| 54 |
|
| 55 |
qemu -usb -device usb-ccid -device ccid-card-emualated |
| 56 |
|
| 57 |
4. Using ccid-card-emulated with certificates |
| 58 |
|
| 59 |
You must create the certificates. This is a one time process. We use NSS |
| 60 |
certificates: |
| 61 |
|
| 62 |
certutil -d /etc/pki/nssdb -x -t "CT,CT,CT" -S -s "CN=cert1" -n cert1 |
| 63 |
|
| 64 |
Note: you must have exactly three certificates. |
| 65 |
|
| 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: |
| 68 |
|
| 69 |
qemu -usb -device usb-ccid -device ccid-card-emulated,backend=certificates,cert1=cert1,cert2=cert2,cert3=cert3 |
| 70 |
|
| 71 |
5. Using ccid-card-passthru with client side hardware |
| 72 |
|
| 73 |
on the host specify the ccid-card-passthru device with a suitable chardev: |
| 74 |
|
| 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 |
| 76 |
|
| 77 |
on the client run vscclient, built when you built the libcacard library: |
| 78 |
libcacard/vscclient <qemu-host> 2001 |
| 79 |
|
| 80 |
6. Using ccid-card-passthru with client side certificates |
| 81 |
|
| 82 |
Run qemu as per #5, and run vscclient as follows: |
| 83 |
(Note: vscclient command line interface is in a state of change) |
| 84 |
|
| 85 |
libcacard/vscclient -e "db=\"/etc/pki/nssdb\" use_hw=no soft=(,Test,CAC,,cert1,cert2,cert3)" <qemu-host> 2001 |
| 86 |
|
| 87 |
7. Passthrough protocol scenario |
| 88 |
|
| 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: |
| 94 |
* detached |
| 95 |
* attached with no card |
| 96 |
* attached with card |
| 97 |
|
| 98 |
A typical interchange is: (the arrow shows who started each exchange, it can be client |
| 99 |
originated or guest originated) |
| 100 |
|
| 101 |
client event | vscclient | passthru | usb-ccid | guest event |
| 102 |
---------------------------------------------------------------------------------------------- |
| 103 |
| VSC_Init | | | |
| 104 |
| VSC_ReaderAdd | | attach | |
| 105 |
| | | | sees new usb device. |
| 106 |
card inserted -> | | | | |
| 107 |
| VSC_ATR | insert | insert | see new card |
| 108 |
| | | | |
| 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 |
| 113 |
... |
| 114 |
[APDU<->APDU repeats several times] |
| 115 |
... |
| 116 |
card removed -> | | | | |
| 117 |
| VSC_CardRemove | remove | remove | card removed |
| 118 |
... |
| 119 |
[(card insert, apdu's, card remove) repeat] |
| 120 |
... |
| 121 |
kill/quit | | | | |
| 122 |
vscclient | | | | |
| 123 |
| VSC_ReaderRemove | | detach | |
| 124 |
| | | | usb device removed. |
| 125 |
|
| 126 |
|
| 127 |
8. libcacard |
| 128 |
|
| 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). |
| 133 |
|
| 134 |
For documentation of cac_card see README in libcacard subdirectory. |
| 135 |
|