new file mode 100644
@@ -0,0 +1,133 @@
+Qemu CCID Device Documentation.
+
+Contents
+1. USB CCID device
+2. Building
+3. Using ccid-card-emulated with hardware
+4. Using ccid-card-emulated with certificates
+5. Using ccid-card-passthru with client side hardware
+6. Using ccid-card-passthru with client side certificates
+7. Passthrough protocol scenario
+8. libcaccard
+
+1. USB CCID device
+
+The USB CCID device is a USB device implementing the CCID specification, which
+lets one connect smart card readers that implement the same spec. For more
+information see the specification:
+
+ Universal Serial Bus
+ Device Class: Smart Card
+ CCID
+ Specification for
+ Integrated Circuit(s) Cards Interface Devices
+ Revision 1.1
+ April 22rd, 2005
+
+Smartcard are used for authentication, single sign on, decryption in
+public/private schemes and digital signatures. A smartcard reader on the client
+cannot be used on a guest with simple usb passthrough since it will then not be
+available on the client, possibly locking the computer when it is "removed". On
+the other hand this device can let you use the smartcard on both the client and
+the guest machine. It is also possible to have a completely virtual smart card
+reader and smart card (i.e. not backed by a physical device) using this device.
+
+2. Building
+
+prerequisites:
+ libcaccard
+
+At the moment there are no binary or source releases, so it has to be retrieved
+from source control:
+
+ git clone git://anongit.freedesktop.org/~alon/cac_card
+
+fedora:
+ yum install nss-devel
+ubuntu:
+ apt-get install libnss3-dev
+ (not tested on ubuntu)
+
+build cac_card:
+ cd cac_card
+ ./configure && make && sudo make install
+
+qemu:
+ ./configure --enable-smartcard && make
+
+Note that if you install to a non default prefix you need to set
+PKG_CONFIG_PATH to compile qemu successfully.
+
+3. Using ccid-card-emulated with hardware
+
+Assuming you have a working smartcard on the host with the current
+user, using NSS, qemu acts as another NSS client using ccid-card-emulated:
+
+ qemu -usb -device usb-ccid -device ccid-card-emualated
+
+4. Using ccid-card-emulated with certificates
+
+You must create the certificates. This is a one time process. We use NSS certificates:
+
+ certutil -d /etc/pki/nssdb -x -t "CT,CT,CT" -S -s "CN=cert1" -n cert1
+
+Note: you must have exactly three certificates.
+
+Assuming the current user can access the certificates (use certutil -L to verify),
+you can use the emulated card type with the certificates backend:
+
+ qemu -usb -device usb-ccid -device ccid-card-emulated,backend=certificates,cert1=cert1,cert2=cert2,cert3=cert3
+
+5. Using ccid-card-passthru with client side hardware
+
+on the host specify the ccid-card-passthru device with a suitable chardev:
+
+ qemu -chardev socket,server,host=0.0.0.0,port=2001,id=ccid,nowait -usb -device usb-ccid -device ccid-card-passthru,chardev=ccid
+
+on the client run vscclient, built when you built the libcaccard library:
+ vscclient <qemu-host> 2001
+
+6. Using ccid-card-passthru with client side certificates
+
+Run qemu as per #5, and run vscclient as follows:
+(Note: vscclient command line interface is in a state of change)
+
+ ./vscclient -e "db=\"/etc/pki/nssdb\" use_hw=no soft=(,Test,CAC,,cert1,cert2,cert3)" <qemu-host> 2001
+
+7. Passthrough protocol scenario
+
+This is a typical interchange of messages when using the passthru card device.
+usb-ccid is a usb device. It defaults to an unattached usb device on startup.
+usb-ccid expects a chardev and expects the protocol defined in cac_card/vscard_common.h to be passed over that.
+A typical interchange is:
+
+client event | vscclient | passthru | usb-ccid | guest event
+----------------------------------------------------------------------------------------------
+ | VSC_Init | | |
+ | VSC_ReaderAdd | | attach |
+ | | | | sees new usb device.
+card inserted | | | |
+ | VSC_ATR | | |
+ | | | | guest operation, APDU transfer via CCID
+ | | VSC_APDU | |
+ | VSC_APDU | | |
+client<->physical | | | |
+card APDU exchange| | | |
+ [APDU<->APDU repeats several times]
+card removed | | | |
+ | VSC_CardRemove | | |
+kill/quit | | | |
+ vscclient | | | |
+ | VSC_ReaderRemove | | detach |
+ | | | | usb device removed.
+
+
+8. libcaccard
+
+ccid-card-passthru and vscclient use libcaccard as the card emulator.
+libcaccard implements a completely virtual CAC (DoD standard for smart cards)
+compliant card and uses NSS to actually retrive certificates and do any
+encryption using the backend (real reader + card or file backed certificates).
+
+For documentation of cac_card see README in libcac_card package.
+