docs/system/devices/ccid.rst

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