[mirror_qemu.git] / docs / ccid.txt

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. libcacard

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

Smartcards 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

The cryptographic functions and access to the physical card is done via the
libcacard library, whose development package must be installed prior to
building QEMU:

In redhat/fedora:
    yum install libcacard-devel
In ubuntu:
    apt-get install libcacard-dev

Configuring and building:
    ./configure --enable-smartcard && make


3. Using ccid-card-emulated with hardware

Assuming you have a working smartcard on the host with the current
user, using libcacard, QEMU acts as another client using ccid-card-emulated:

    qemu -usb -device usb-ccid -device ccid-card-emulated


4. Using ccid-card-emulated with certificates stored in files

You must create the CA and card certificates. This is a one time process.
We use NSS certificates:

    mkdir fake-smartcard
    cd fake-smartcard
    certutil -N -d sql:$PWD
    certutil -S -d sql:$PWD -s "CN=Fake Smart Card CA" -x -t TC,TC,TC -n fake-smartcard-ca
    certutil -S -d sql:$PWD -t ,, -s "CN=John Doe" -n id-cert -c fake-smartcard-ca
    certutil -S -d sql:$PWD -t ,, -s "CN=John Doe (signing)" --nsCertType smime -n signing-cert -c fake-smartcard-ca
    certutil -S -d sql:$PWD -t ,, -s "CN=John Doe (encryption)" --nsCertType sslClient -n encryption-cert -c fake-smartcard-ca

Note: you must have exactly three certificates.

You can use the emulated card type with the certificates backend:

    qemu -usb -device usb-ccid -device ccid-card-emulated,backend=certificates,db=sql:$PWD,cert1=id-cert,cert2=signing-cert,cert3=encryption-cert

To use the certificates in the guest, export the CA certificate:

    certutil -L -r -d sql:$PWD -o fake-smartcard-ca.cer -n fake-smartcard-ca

and import it in the guest:

    certutil -A -d /etc/pki/nssdb -i fake-smartcard-ca.cer -t TC,TC,TC -n fake-smartcard-ca

In a Linux guest you can then use the CoolKey PKCS #11 module to access
the card:

    certutil -d /etc/pki/nssdb -L -h all

It will prompt you for the PIN (which is the password you assigned to the
certificate database early on), and then show you all three certificates
together with the manually imported CA cert:

    Certificate Nickname                        Trust Attributes
    fake-smartcard-ca                           CT,C,C
    John Doe:CAC ID Certificate                 u,u,u
    John Doe:CAC Email Signature Certificate    u,u,u
    John Doe:CAC Email Encryption Certificate   u,u,u

If this does not happen, CoolKey is not installed or not registered with
NSS.  Registration can be done from Firefox or the command line:

    modutil -dbdir /etc/pki/nssdb -add "CAC Module" -libfile /usr/lib64/pkcs11/libcoolkeypk11.so
    modutil -dbdir /etc/pki/nssdb -list


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=on,host=0.0.0.0,port=2001,id=ccid,wait=off \
         -usb -device usb-ccid -device ccid-card-passthru,chardev=ccid

on the client run vscclient, built when you built QEMU:

    vscclient <qemu-host> 2001


6. Using ccid-card-passthru with client side certificates

This case is not particularly useful, but you can use it to debug
your setup if #4 works but #5 does not.

Follow instructions as per #4, except run QEMU and vscclient as follows:
Run qemu as per #5, and run vscclient from the "fake-smartcard"
directory as follows:

    qemu -chardev socket,server=on,host=0.0.0.0,port=2001,id=ccid,wait=off \
         -usb -device usb-ccid -device ccid-card-passthru,chardev=ccid
    vscclient -e "db=\"sql:$PWD\" use_hw=no soft=(,Test,CAC,,id-cert,signing-cert,encryption-cert)" <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.
The usb-ccid device can be in one of three modes:
 * detached
 * attached with no card
 * attached with card

A typical interchange is: (the arrow shows who started each exchange, it can be client
originated or guest originated)

client event      |      vscclient           |    passthru    |     usb-ccid  |  guest event
----------------------------------------------------------------------------------------------
                  |      VSC_Init            |                |               |
                  |      VSC_ReaderAdd       |                |     attach    |
                  |                          |                |               |  sees new usb device.
card inserted ->  |                          |                |               |
                  |      VSC_ATR             |   insert       |     insert    |  see new card
                  |                          |                |               |
                  |      VSC_APDU            |   VSC_APDU     |               | <- guest sends APDU
client<->physical |                          |                |               |
card APDU exchange|                          |                |               |
client response ->|      VSC_APDU            |   VSC_APDU     |               |  receive APDU response
                                                    ...
                                    [APDU<->APDU repeats several times]
                                                    ...
card removed  ->  |                          |                |               |
                  |      VSC_CardRemove      |   remove       |    remove     |   card removed
                                                    ...
                                    [(card insert, apdu's, card remove) repeat]
                                                    ...
kill/quit         |                          |                |               |
  vscclient       |                          |                |               |
                  |      VSC_ReaderRemove    |                |    detach     |
                  |                          |                |               |   usb device removed.


8. libcacard

Both ccid-card-emulated and vscclient use libcacard as the card emulator.
libcacard implements a completely virtual CAC (DoD standard for smart
cards) compliant card and uses NSS to retrieve certificates and do
any encryption.  The backend can then be a real reader and card, or
certificates stored in files.

For documentation of the library see docs/libcacard.txt.
Commit	Line	Data
6576b74b	1	QEMU CCID Device Documentation.
1056c02b AL	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
e03ba136	27	Smartcards are used for authentication, single sign on, decryption in
1056c02b AL	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
51f5c849 DB	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:
1056c02b AL	40
1056c02b AL	41	In redhat/fedora:
51f5c849 DB	42	yum install libcacard-devel
	43	In ubuntu:
	44	apt-get install libcacard-dev
1056c02b AL	45
	46	Configuring and building:
	47	./configure --enable-smartcard && make
	48
471f7e30	49
1056c02b AL	50	3. Using ccid-card-emulated with hardware
	51
	52	Assuming you have a working smartcard on the host with the current
51f5c849	53	user, using libcacard, QEMU acts as another client using ccid-card-emulated:
1056c02b	54
5f32804c	55	qemu -usb -device usb-ccid -device ccid-card-emulated
1056c02b	56
1056c02b	57
471f7e30 PB	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:
1056c02b	62
471f7e30 PB	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
1056c02b AL	70
	71	Note: you must have exactly three certificates.
	72
471f7e30 PB	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
1056c02b	105
1056c02b AL	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
c2387413 DB	111	qemu -chardev socket,server=on,host=0.0.0.0,port=2001,id=ccid,wait=off \
c2387413 DB	112	-usb -device usb-ccid -device ccid-card-passthru,chardev=ccid
1056c02b	113
471f7e30 PB	114	on the client run vscclient, built when you built QEMU:
	115
	116	vscclient <qemu-host> 2001
	117
1056c02b AL	118
	119	6. Using ccid-card-passthru with client side certificates
	120
471f7e30 PB	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
c2387413 DB	128	qemu -chardev socket,server=on,host=0.0.0.0,port=2001,id=ccid,wait=off \
c2387413 DB	129	-usb -device usb-ccid -device ccid-card-passthru,chardev=ccid
471f7e30	130	vscclient -e "db=\"sql:$PWD\" use_hw=no soft=(,Test,CAC,,id-cert,signing-cert,encryption-cert)" <qemu-host> 2001
1056c02b	131
1056c02b AL	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
471f7e30 PB	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.
1056c02b	180
471f7e30	181	For documentation of the library see docs/libcacard.txt.
1056c02b	182