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 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-emulated
  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