Patchwork [5/5] smartcard: add docs

mail settings
Submitter Alon Levy
Date Dec. 12, 2010, 6:37 p.m.
Message ID <>
Download mbox | patch
Permalink /patch/75267/
State New
Headers show


Alon Levy - Dec. 12, 2010, 6:37 p.m.
 docs/ccid.txt      |  125 ++++++++++++++
 2 files changed, 608 insertions(+), 0 deletions(-)
 create mode 100644 docs/ccid.txt
 create mode 100644 docs/libcacard.txt
Gerd Hoffmann - Dec. 15, 2010, 12:39 p.m.


Move this to the libcacard patch and add a pointer to it to the commit 



diff --git a/docs/ccid.txt b/docs/ccid.txt
new file mode 100644
index 0000000..791c28c
--- /dev/null
+++ b/docs/ccid.txt
@@ -0,0 +1,125 @@ 
+Qemu CCID Device Documentation.
+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. libcaccard
+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
+ Specification for
+ Integrated Circuit(s) Cards Interface Devices
+ Revision 1.1
+ April 22rd, 2005
+Smartcard 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 NSS.
+Installing NSS:
+In redhat/fedora:
+    yum install nss-devel
+In ubuntu/debian:
+    apt-get install libnss3-dev
+    (not tested on ubuntu)
+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 NSS, qemu acts as another NSS client using ccid-card-emulated:
+    qemu -usb -device usb-ccid -device ccid-card-emualated
+4. Using ccid-card-emulated with certificates
+You must create the certificates. This is a one time process. We use NSS
+    certutil -d /etc/pki/nssdb -x -t "CT,CT,CT" -S -s "CN=cert1" -n cert1
+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:
+    qemu -usb -device usb-ccid -device ccid-card-emulated,backend=certificates,cert1=cert1,cert2=cert2,cert3=cert3
+on the host specify the ccid-card-passthru device with a suitable chardev:
+    qemu -chardev socket,server,host=,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 libcaccard library:
+    libcaccard/vscclient <qemu-host> 2001
+Run qemu as per #5, and run vscclient as follows:
+(Note: vscclient command line interface is in a state of change)
+    libcaccard/vscclient -e "db=\"/etc/pki/nssdb\" use_hw=no soft=(,Test,CAC,,cert1,cert2,cert3)" <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.
+A typical interchange is:
+client event      |      vscclient           |    passthru    |     usb-ccid  |  guest event
+                  |      VSC_Init            |                |               |
+                  |      VSC_ReaderAdd       |                |     attach    |
+                  |                          |                |               |  sees new usb device.
+card inserted     |                          |                |               |
+                  |      VSC_ATR             |                |               |
+                  |                          |                |               |  guest operation, APDU transfer via CCID
+                  |                          |   VSC_APDU     |               |
+                  |      VSC_APDU            |                |               |
+client<->physical |                          |                |               |
+card APDU exchange|                          |                |               |
+                            [APDU<->APDU repeats several times]
+card removed      |                          |                |               |
+                  |      VSC_CardRemove      |                |               |
+kill/quit         |                          |                |               |
+  vscclient       |                          |                |               |
+                  |      VSC_ReaderRemove    |                |    detach     |
+                  |                          |                |               |   usb device removed.
+8. libcaccard
+ccid-card-passthru and vscclient use libcaccard as the card emulator.
+libcaccard 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).
+For documentation of cac_card see README in libcaccard subdirectory.
new file mode 100644
index 0000000..5dee6fa
--- /dev/null
+++ b/docs/libcacard.txt
@@ -0,0 +1,483 @@ 
+Virtual Smart Card Emulator
+the cards could be pure software constructs.
+modifications are:
+this is in vscclient.c.
+this is in vcard_emul_nss.c.
+Replacing the Socket Based Virtual Reader Interface.
+The current implementation contains a replacable module vscclient.c. The
+current vscclient.c implements a sockets interface to the virtual ccid reader
+The protocol that vscclient uses is defined in vscard_common.h and connects
+the emulator.
+that the CCID reader can call are:
+      VReaderList * vreader_get_reader_list();
+  needed.
+      VReaderListEntry *vreader_list_get_first(VReaderList *);
+  reader list returned from vreader_get_reader_list(). VReaderListEntries are
+      VReaderListEntry *vreader_list_get_next(VReaderListEntry *);
+  it will return NULL.
+      VReader * vreader_list_get_reader(VReaderListEntry *)
+  finished with vreader_free().
+      void vreader_free(VReader *reader);
+   and are automatically deleted when the last reference is freed.
+      void vreader_list_delete(VReaderList *list);
+   reader references held by the list.
+  returned ATR.
+      VReaderStatus vreader_power_off(VReader *reader);
+  This function simulates a power off of a virtual card.
+                                       int send_buf_len,
+                                       unsigned char *receive_buf,
+                                       int receive_buf_len);
+  is driven from these APDUs.
+      VReaderStatus vreader_card_is_present(VReader *reader);
+  vreader_power_on, vreader_power_off, and vreader_xfer_bytes will return
+       const char *vreader_get_name(VReader *reader);
+       VReaderID vreader_get_id(VReader *reader);
+       VReaderStatus vreader_get_id(VReader *reader, VReaderID id);
+       VReader *vreader_find_reader_by_id(VReaderID id);
+       Event *vevent_wait_next_vevent();
+       Event *vevent_get_next_vevent();
+  NULL. It does not block.
+Card Type Emulator: Adding a New Virtual Card Type
+The ISO 7816 card spec describes 2 types of cards:
+implemented for file system cards.
+functions. The current implementation supports VM cards.
+public entry point:
+                               const unsigned char *cert[],
+                               int cert_len[],
+                               VCardKey *key[],
+                               int cert_count);
+  The parameters for this are:
+  cert       - array of binary certificates.
+               the card.
+the card using the following functions:
+       VCardApplet *vcard_new_applet(VCardProcessAPDU apdu_func,
+                                     VCardResetApplet reset_func,
+                                     const unsigned char *aid,
+                                     int aid_len);
+  information:
+        this below).
+        (set by reset_func, more on this below).
+        separate call).
+        data when the applet itself is destroyed.
+        void vcard_set_applet_private(VCardApplet *applet,
+                                      VCardAppletPrivate *private,
+                                      VCardAppletPrivateFree private_free);
+  passing two NULL clear any existing private data.
+  may have the same VCardPRocessAPDU entry point.
+emulators once one of its applets are selected through the VCardProcessAPDU
+function it specified when it created the applet.
+The signature of VCardResetApplet is:
+The signature of VCardProcessAPDU is:
+                                         VCardResponse **response);
+  This function examines the APDU and determines whether it should process
+  the basic 7816 emulator for processing.
+  should return VCARD_NEXT.
+  response using vcard_make_response and the appropriate 7816 error code
+  code. It should then return VCARD_DONE.
+  VCardProcessAPDU should always set the response if it returns VCARD_DONE.
+  It should always either return VCARD_DONE or VCARD_NEXT.
+Parsing the APDU --
+   apdu->a_data - The raw apdu data bytes.
+   apdu->a_Lc   - The parameter length value.
+   apdu->a_cla  - The raw apdu class.
+   apdu->a_secure_messaging_type - The decoded secure messagin type
+                                   (from class).
+   apdu->a_type - The decode class type.
+   apdu->a_ins  - The instruction byte.
+   apdu->a_p1   - Parameter 1.
+   apdu->a_p2   - Parameter 2.
+Creating a Response --
+create card responses.
+        VCardResponse *vcard_make_response(VCard7816Status status);
+    is passed and vcard_make_response fails to allocate the appropriate memory
+    for that response, then vcard_make_response will return a VCardResponse
+    of VCARD7816_STATUS_EXC_ERROR_MEMORY. In any case, this function is
+    guarrenteed to return a valid VCardResponse.
+                                          VCard7816Status status);
+    This function is similar to vcard_make_response except it includes some
+    memory, in which case it will return NULL.
+        VCardResponse *vcard_response_new_status_bytes(unsigned char sw1,
+                                                       unsigned char sw2);
+    NULL.
+                                               unsigned char sw1,
+                                               unsigned char sw2);
+    This function is the same as vcard_response_new except you may specify
+    the status as two separate bytes like vcard_response_new_status_bytes.
+Implementing functionality ---
+The following helper functions access information about the current card
+and applet.
+        VCARDAppletPrivate *vcard_get_current_applet_private(VCard *card,
+                                                             int channel);
+    with a particular applet is also stored here.
+        int vcard_emul_get_login_count(VCard *card);
+                                          int pin_len);
+    word depending on the success or failure of the call.
+         void vcard_emul_delete_key(VCardKey *key);
+     it.
+         VCard7816Status vcard_emul_rsa_op(VCard *card, VCardKey *key,
+                                           unsigned char *buffer,
+                                           int buffer_size);
+card according to the CAC specs should be implemented here.
+Virtual Card Emulator
+virtual card implementation at a time.
+addition to the services describe above (services starting with
+vcard_emul_xxxx), the virtual card emulator also provides the following
+    VCardEmulError vcard_emul_init(cont VCardEmulOptions *options);
+  interface where a string of virtual card emulator specific strings are
+  determine which physical cards to present to the guest.
+  have cards present in them, they are also initialized.
+  Readers are created with the function.
+          VReader *vreader_new(VReaderEmul *reader_emul,
+                               VReaderEmulFree reader_emul_free);
+      destroyed.  The VReaderEmul structure is an opaque structure to the
+      use it to store any reader specific state.
+  call:
+           VReaderStatus vreader_add_reader(VReader *reader);
+      This function will automatically generate the appropriate new reader
+      events and add the reader to the list.
+  function.
+           VCard *vcard_new(VCardEmul *card_emul,
+                            VCardEmulFree card_emul_free);
+      Like vreader_new, this function takes a virtual card emulator specific
+  following function:
+            VCardStatus vcard_init(VCard *vcard, VCardEmulType type,
+                                   const char *flags,
+                                   unsigned char *const *certs,
+                                   int *cert_len,
+                                   VCardKey *key[],
+                                   int cert_count);
+      the same of the parameters xxxx_card_init() accepts.
+      notification for the card insert.
+    VCardEmulError vcard_emul_force_card_remove(VReader *vreader);
+  that card is a physical card and is present.
+    VCardEmulError vcard_emul_force_card_insert(VReader *reader);
+  Force a card that has been removed by vcard_emul_force_card_remove to be
+  particular emulator. For instance the NSS emulator returns
+     void vcard_emul_reset(VCard *card, VCardPower power)
+   state (logout, etc).
+List of files and their function:
+README - This file
+card_7816.h - apdu and response services definitions.
+card_7816t.h - 7816 specific structures, types and definitions.
+event.c - event handling code.
+event.h - event handling services definitions.
+eventt.h - event handling structures and types
+          applet management.
+vcard.h - common virtual card services function definitions.
+vcardt.h - comon virtual card types
+vreader.c - common virtual reader services.
+vreader.h - common virtual reader services definitions.
+vreadert.h - comon virtual reader types.
+vcard_emul_type.c - manage the card type emulators.
+vcard_emul_type.h - definitions for card type emulators.
+cac.c - card type emulator for CAC cards
+vcard_emul.h - virtual card emulator service definitions.
+vcard_emul_nss.c - virtual card emulator implementation for nss.
+vscclient.c - socket connection to guest qemu usb driver.
+vscard_common.h - common header with the guest qemu usb driver.
+mutex.h - header file for machine independent mutexes.