[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH] libcacard: improve documentation
From: |
Alon Levy |
Subject: |
Re: [Qemu-devel] [PATCH] libcacard: improve documentation |
Date: |
Thu, 29 May 2014 14:22:13 +0300 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.5.0 |
On 05/28/2014 07:15 PM, Paolo Bonzini wrote:
> Using the file-backed smartcard backend is black magic, but it can
> be useful if your only smartcard bricks itself if it is accessed
> the wrong way too many times.
>
> Complete the documentation to include the art of creating certificates
> and using them with QEMU, based on Ray Strode's useful tutorial at
> https://blogs.gnome.org/halfline/2013/09/08/another-smartcard-post/
> but with ccid-card-emulated or vscclient instead of SPICE.
>
> Cc: Alon Levy <address@hidden>
> Cc: Ray Strode <address@hidden>
Did you mean Robert Relyea <address@hidden> ?
Thanks, looks good.
Reviewed-by: Alon Levy <address@hidden>
> Signed-off-by: Paolo Bonzini <address@hidden>
> ---
> docs/ccid.txt | 80
> ++++++++++++++++++++++++++++++++++++++++++++++-------------
> 1 file changed, 63 insertions(+), 17 deletions(-)
>
> diff --git a/docs/ccid.txt b/docs/ccid.txt
> index 83c174d..c7fda6d 100644
> --- a/docs/ccid.txt
> +++ b/docs/ccid.txt
> @@ -47,6 +47,7 @@ In ubuntu/debian:
> 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
> @@ -54,19 +55,55 @@ user, using NSS, qemu acts as another NSS client using
> ccid-card-emulated:
>
> qemu -usb -device usb-ccid -device ccid-card-emulated
>
> -4. Using ccid-card-emulated with certificates
>
> -You must create the certificates. This is a one time process. We use NSS
> -certificates:
> +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:
>
> - certutil -d /etc/pki/nssdb -x -t "CT,CT,CT" -S -s "CN=cert1" -n cert1
> + 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.
>
> -Assuming the current user can access the certificates (use certutil -L to
> -verify), you can use the emulated card type with the certificates backend:
> +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
>
> - qemu -usb -device usb-ccid -device
> ccid-card-emulated,backend=certificates,cert1=cert1,cert2=cert2,cert3=cert3
>
> 5. Using ccid-card-passthru with client side hardware
>
> @@ -74,15 +111,23 @@ on the host specify the ccid-card-passthru device with a
> suitable chardev:
>
> qemu -chardev socket,server,host=0.0.0.0,port=2001,id=ccid,nowait -usb
> -device usb-ccid -device ccid-card-passthru,chardev=ccid
>
> -on the client run vscclient, built when you built the libcacard library:
> - libcacard/vscclient <qemu-host> 2001
> +on the client run vscclient, built when you built QEMU:
> +
> + vscclient <qemu-host> 2001
> +
>
> 6. Using ccid-card-passthru with client side certificates
>
> -Run qemu as per #5, and run vscclient as follows:
> -(Note: vscclient command line interface is in a state of change)
> +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,host=0.0.0.0,port=2001,id=ccid,nowait -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
>
> - libcacard/vscclient -e "db=\"/etc/pki/nssdb\" use_hw=no
> soft=(,Test,CAC,,cert1,cert2,cert3)" <qemu-host> 2001
>
> 7. Passthrough protocol scenario
>
> @@ -126,10 +171,11 @@ kill/quit | |
> | |
>
> 8. libcacard
>
> -ccid-card-passthru 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 actually retrive certificates and do any
> -encryption using the backend (real reader + card or file backed
> certificates).
> +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 cac_card see README in libcacard subdirectory.
> +For documentation of the library see docs/libcacard.txt.
>
>