docs/ccid: convert to restructuredText
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
Thomas Huth
parent
5b4f72f5e8
commit
4667619269
182
docs/ccid.txt
182
docs/ccid.txt
@ -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.
|
|
||||||
|
|
||||||
@ -83,6 +83,7 @@ Emulated Devices
|
|||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
devices/can.rst
|
devices/can.rst
|
||||||
|
devices/ccid.rst
|
||||||
devices/ivshmem.rst
|
devices/ivshmem.rst
|
||||||
devices/net.rst
|
devices/net.rst
|
||||||
devices/nvme.rst
|
devices/nvme.rst
|
||||||
|
|||||||
171
docs/system/devices/ccid.rst
Normal file
171
docs/system/devices/ccid.rst
Normal 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.
|
||||||
Loading…
x
Reference in New Issue
Block a user