| Message ID | 20220405142906.21382-1-oxr463@gmx.us (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs/ccid: convert to restructuredText | expand |
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 >
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. +