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