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 27Smartcard 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 NSS. 38 39Installing NSS: 40 41In redhat/fedora: 42 yum install nss-devel 43In ubuntu/debian: 44 apt-get install libnss3-dev 45 (not tested on ubuntu) 46 47Configuring and building: 48 ./configure --enable-smartcard && make 49 503. Using ccid-card-emulated with hardware 51 52Assuming you have a working smartcard on the host with the current 53user, using NSS, qemu acts as another NSS client using ccid-card-emulated: 54 55 qemu -usb -device usb-ccid -device ccid-card-emualated 56 574. Using ccid-card-emulated with certificates 58 59You must create the certificates. This is a one time process. We use NSS 60certificates: 61 62 certutil -d /etc/pki/nssdb -x -t "CT,CT,CT" -S -s "CN=cert1" -n cert1 63 64Note: you must have exactly three certificates. 65 66Assuming the current user can access the certificates (use certutil -L to 67verify), 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 715. Using ccid-card-passthru with client side hardware 72 73on 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 77on the client run vscclient, built when you built the libcacard library: 78 libcacard/vscclient <qemu-host> 2001 79 806. Using ccid-card-passthru with client side certificates 81 82Run 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 877. Passthrough protocol scenario 88 89This is a typical interchange of messages when using the passthru card device. 90usb-ccid is a usb device. It defaults to an unattached usb device on startup. 91usb-ccid expects a chardev and expects the protocol defined in 92cac_card/vscard_common.h to be passed over that. 93The usb-ccid device can be in one of three modes: 94 * detached 95 * attached with no card 96 * attached with card 97 98A typical interchange is: (the arrow shows who started each exchange, it can be client 99originated or guest originated) 100 101client event | vscclient | passthru | usb-ccid | guest event 102---------------------------------------------------------------------------------------------- 103 | VSC_Init | | | 104 | VSC_ReaderAdd | | attach | 105 | | | | sees new usb device. 106card inserted -> | | | | 107 | VSC_ATR | insert | insert | see new card 108 | | | | 109 | VSC_APDU | VSC_APDU | | <- guest sends APDU 110client<->physical | | | | 111card APDU exchange| | | | 112client response ->| VSC_APDU | VSC_APDU | | receive APDU response 113 ... 114 [APDU<->APDU repeats several times] 115 ... 116card removed -> | | | | 117 | VSC_CardRemove | remove | remove | card removed 118 ... 119 [(card insert, apdu's, card remove) repeat] 120 ... 121kill/quit | | | | 122 vscclient | | | | 123 | VSC_ReaderRemove | | detach | 124 | | | | usb device removed. 125 126 1278. libcacard 128 129ccid-card-passthru and vscclient use libcacard as the card emulator. 130libcacard implements a completely virtual CAC (DoD standard for smart cards) 131compliant card and uses NSS to actually retrive certificates and do any 132encryption using the backend (real reader + card or file backed certificates). 133 134For documentation of cac_card see README in libcacard subdirectory. 135 136