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 the
  38 libcacard library, whose development package must be installed prior to
  39 building QEMU:
  40
  41 In redhat/fedora:
  42     yum install libcacard-devel
  43 In ubuntu:
  44     apt-get install libcacard-dev
  45
  46 Configuring and building:
  47     ./configure --enable-smartcard && make
  48
  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 libcacard, QEMU acts as another client using ccid-card-emulated:
  54
  55     qemu -usb -device usb-ccid -device ccid-card-emulated
  56
  57
  58 4. Using ccid-card-emulated with certificates stored in files
  59
  60 You must create the CA and card certificates. This is a one time process.
  61 We 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
  71 Note: you must have exactly three certificates.
  72
  73 You 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
  77 To 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
  81 and 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
  85 In a Linux guest you can then use the CoolKey PKCS #11 module to access
  86 the card:
  87
  88     certutil -d /etc/pki/nssdb -L -h all
  89
  90 It will prompt you for the PIN (which is the password you assigned to the
  91 certificate database early on), and then show you all three certificates
  92 together 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
 100 If this does not happen, CoolKey is not installed or not registered with
 101 NSS.  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
 107 5. Using ccid-card-passthru with client side hardware
 108
 109 on 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
 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=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
 133 7. Passthrough protocol scenario
 134
 135 This is a typical interchange of messages when using the passthru card device.
 136 usb-ccid is a usb device. It defaults to an unattached usb device on startup.
 137 usb-ccid expects a chardev and expects the protocol defined in
 138 cac_card/vscard_common.h to be passed over that.
 139 The usb-ccid device can be in one of three modes:
 140  * detached
 141  * attached with no card
 142  * attached with card
 143
 144 A typical interchange is: (the arrow shows who started each exchange, it can be client
 145 originated or guest originated)
 146
 147 client event      |      vscclient           |    passthru    |     usb-ccid  |  guest event
 148 ----------------------------------------------------------------------------------------------
 149                   |      VSC_Init            |                |               |
 150                   |      VSC_ReaderAdd       |                |     attach    |
 151                   |                          |                |               |  sees new usb device.
 152 card inserted ->  |                          |                |               |
 153                   |      VSC_ATR             |   insert       |     insert    |  see new card
 154                   |                          |                |               |
 155                   |      VSC_APDU            |   VSC_APDU     |               | <- guest sends APDU
 156 client<->physical |                          |                |               |
 157 card APDU exchange|                          |                |               |
 158 client response ->|      VSC_APDU            |   VSC_APDU     |               |  receive APDU response
 159                                                     ...
 160                                     [APDU<->APDU repeats several times]
 161                                                     ...
 162 card removed  ->  |                          |                |               |
 163                   |      VSC_CardRemove      |   remove       |    remove     |   card removed
 164                                                     ...
 165                                     [(card insert, apdu's, card remove) repeat]
 166                                                     ...
 167 kill/quit         |                          |                |               |
 168   vscclient       |                          |                |               |
 169                   |      VSC_ReaderRemove    |                |    detach     |
 170                   |                          |                |               |   usb device removed.
 171
 172
 173 8. libcacard
 174
 175 Both ccid-card-emulated and vscclient use libcacard as the card emulator.
 176 libcacard implements a completely virtual CAC (DoD standard for smart
 177 cards) compliant card and uses NSS to retrieve certificates and do
 178 any encryption.  The backend can then be a real reader and card, or
 179 certificates stored in files.
 180
 181 For documentation of the library see docs/libcacard.txt.
 182