docs/ccid.txt | 182 ------------------------------- docs/system/device-emulation.rst | 1 + docs/system/devices/ccid.rst | 171 +++++++++++++++++++++++++++++ 3 files changed, 172 insertions(+), 182 deletions(-) delete mode 100644 docs/ccid.txt create mode 100644 docs/system/devices/ccid.rst
From: Lucas Ramage <lucas.ramage@infinite-omicron.com>
Buglink: https://gitlab.com/qemu-project/qemu/-/issues/527
Signed-off-by: Lucas Ramage <lucas.ramage@infinite-omicron.com>
---
docs/ccid.txt | 182 -------------------------------
docs/system/device-emulation.rst | 1 +
docs/system/devices/ccid.rst | 171 +++++++++++++++++++++++++++++
3 files changed, 172 insertions(+), 182 deletions(-)
delete mode 100644 docs/ccid.txt
create mode 100644 docs/system/devices/ccid.rst
diff --git a/docs/ccid.txt b/docs/ccid.txt
deleted file mode 100644
index 2b85b1bd42..0000000000
--- a/docs/ccid.txt
+++ /dev/null
@@ -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.
-
diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst
index 0b3a3d73ad..ae8dd233e8 100644
--- a/docs/system/device-emulation.rst
+++ b/docs/system/device-emulation.rst
@@ -83,6 +83,7 @@ Emulated Devices
:maxdepth: 1
devices/can.rst
+ devices/ccid.rst
devices/ivshmem.rst
devices/net.rst
devices/nvme.rst
diff --git a/docs/system/devices/ccid.rst b/docs/system/devices/ccid.rst
new file mode 100644
index 0000000000..0290265a18
--- /dev/null
+++ b/docs/system/devices/ccid.rst
@@ -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.
+
--
2.34.1
On 4/5/22 16:29, oxr463@gmx.us wrote: > From: Lucas Ramage <lucas.ramage@infinite-omicron.com> > > Buglink: https://gitlab.com/qemu-project/qemu/-/issues/527 > Signed-off-by: Lucas Ramage <lucas.ramage@infinite-omicron.com> Provided 2 minors tweaks (see below: missing empty line, and empty line at EOF), Reviewed-by: Damien Hedde <damien.hedde@greensocs.com> Note that I'm not competent regarding the content of this doc. But it corresponds to the previous version and the doc generation works. > --- > docs/ccid.txt | 182 ------------------------------- > docs/system/device-emulation.rst | 1 + > docs/system/devices/ccid.rst | 171 +++++++++++++++++++++++++++++ > 3 files changed, 172 insertions(+), 182 deletions(-) > delete mode 100644 docs/ccid.txt > create mode 100644 docs/system/devices/ccid.rst > > diff --git a/docs/ccid.txt b/docs/ccid.txt > deleted file mode 100644 > index 2b85b1bd42..0000000000 > --- a/docs/ccid.txt > +++ /dev/null > @@ -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. > - > diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst > index 0b3a3d73ad..ae8dd233e8 100644 > --- a/docs/system/device-emulation.rst > +++ b/docs/system/device-emulation.rst > @@ -83,6 +83,7 @@ Emulated Devices > :maxdepth: 1 > > devices/can.rst > + devices/ccid.rst > devices/ivshmem.rst > devices/net.rst > devices/nvme.rst > diff --git a/docs/system/devices/ccid.rst b/docs/system/devices/ccid.rst > new file mode 100644 > index 0000000000..0290265a18 > --- /dev/null > +++ b/docs/system/devices/ccid.rst > @@ -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: Empty line missing here, so that the bullet list below works. > +* 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. > + Empty line at end of line should be removed I think. > -- > 2.34.1 > > Regards, -- Damien
On 05/04/2022 17.37, Damien Hedde wrote: > > > On 4/5/22 16:29, oxr463@gmx.us wrote: >> From: Lucas Ramage <lucas.ramage@infinite-omicron.com> >> >> Buglink: https://gitlab.com/qemu-project/qemu/-/issues/527 >> Signed-off-by: Lucas Ramage <lucas.ramage@infinite-omicron.com> > > Provided 2 minors tweaks (see below: missing empty line, and empty line at > EOF), > Reviewed-by: Damien Hedde <damien.hedde@greensocs.com> > > Note that I'm not competent regarding the content of this doc. But it > corresponds to the previous version and the doc generation works. CCID is also not really my turf, but I can take it through my tree if nobody else wants to take it (and make the two suggested corrections while picking it up). Thomas >> --- >> docs/ccid.txt | 182 ------------------------------- >> docs/system/device-emulation.rst | 1 + >> docs/system/devices/ccid.rst | 171 +++++++++++++++++++++++++++++ >> 3 files changed, 172 insertions(+), 182 deletions(-) >> delete mode 100644 docs/ccid.txt >> create mode 100644 docs/system/devices/ccid.rst >> >> diff --git a/docs/ccid.txt b/docs/ccid.txt >> deleted file mode 100644 >> index 2b85b1bd42..0000000000 >> --- a/docs/ccid.txt >> +++ /dev/null >> @@ -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. >> - >> diff --git a/docs/system/device-emulation.rst >> b/docs/system/device-emulation.rst >> index 0b3a3d73ad..ae8dd233e8 100644 >> --- a/docs/system/device-emulation.rst >> +++ b/docs/system/device-emulation.rst >> @@ -83,6 +83,7 @@ Emulated Devices >> :maxdepth: 1 >> >> devices/can.rst >> + devices/ccid.rst >> devices/ivshmem.rst >> devices/net.rst >> devices/nvme.rst >> diff --git a/docs/system/devices/ccid.rst b/docs/system/devices/ccid.rst >> new file mode 100644 >> index 0000000000..0290265a18 >> --- /dev/null >> +++ b/docs/system/devices/ccid.rst >> @@ -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: > > Empty line missing here, so that the bullet list below works. > >> +* 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. >> + > > Empty line at end of line should be removed I think. > >> -- >> 2.34.1 >> >> > > Regards, > -- > Damien >
© 2016 - 2024 Red Hat, Inc.