mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/ccid: convert to restructuredText

Browse Source 
Buglink: https://gitlab.com/qemu-project/qemu/-/issues/527
Signed-off-by: Lucas Ramage <lucas.ramage@infinite-omicron.com>
Message-Id: <20220405142906.21382-1-oxr463@gmx.us>
Reviewed-by: Damien Hedde <damien.hedde@greensocs.com>
[thuth: Added some cosmetic fixes]
Signed-off-by: Thomas Huth <thuth@redhat.com>
This commit is contained in:
Lucas Ramage 2022-04-05 14:29:06 +00:00 committed by Thomas Huth
parent 5b4f72f5e8
commit 4667619269
3 changed files with 172 additions and 182 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
docs/ccid.txt
View File

@ -1,182 +0,0 @@
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.

1
docs/system/device-emulation.rst
View File

@ -83,6 +83,7 @@ Emulated Devices
:maxdepth: 1
devices/can.rst
devices/ccid.rst
devices/ivshmem.rst
devices/net.rst
devices/nvme.rst

171
docs/system/devices/ccid.rst Normal file
View File

@ -0,0 +1,171 @@
Chip Card Interface Device (CCID)
=================================
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.
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
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
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
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
Using ccid-card-passthru with client side certificates
------------------------------------------------------
This case is not particularly useful, but you can use it to debug
your setup.
Follow instructions above, except run QEMU and vscclient as follows.
Run qemu as per above, 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
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.
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.