From dedb627e820c53efd897e669a9d488426c477aad Mon Sep 17 00:00:00 2001 From: frankmorgner Date: Thu, 8 Dec 2011 23:03:40 +0000 Subject: [PATCH] documentation git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@654 96b47cad-a561-4643-ad3b-153ac7d7599c --- virtualsmartcard/doc/api.rst | 72 ++++++++++++++++++++++++++- virtualsmartcard/doc/virtualsmartcard | 1 + 2 files changed, 72 insertions(+), 1 deletion(-) create mode 120000 virtualsmartcard/doc/virtualsmartcard diff --git a/virtualsmartcard/doc/api.rst b/virtualsmartcard/doc/api.rst index 41685d1..1ef69c6 100644 --- a/virtualsmartcard/doc/api.rst +++ b/virtualsmartcard/doc/api.rst @@ -1,10 +1,18 @@ .. |vpicc| replace:: :abbr:`vpicc (virtual smart card)` .. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)` +.. |APDU| replace:: :abbr:`APDU (Application Protocol Data Unit)` +.. |SWs| replace:: :abbr:`SWs (status bytes SW 1 and SW 2)` +.. |SAM| replace:: :abbr:`SAM (Secure Access Module)` ***************************** -Creating a virtual smart card +Creating a Virtual Smart Card ***************************** +|vpcd| communicates over a socked with |vpicc| usually on port ``0x8C7B`` +(configurably via :file:`/etc/reader.conf.d/vpcd`). So you can connect +virtually any program to the virtual smart card reader, as long as you respect +the following protocol: + ============= ==================== ============= ============= |vpcd| |vpicc| ---------------------------------- --------------------------- @@ -17,6 +25,68 @@ Length Command Length Response ``0xXX 0xXX`` (APDU) ``0xXX 0xXX`` (R-APDU) ============= ==================== ============= ============= +The communication is initiated by |vpcd|. First the length of the data (in +network byte order, i.e. little endian) is sent followed by the data itself. + + +======================================= +Implementing a ISO 7816 like Smart Card +======================================= + +|vpicc| includes an emulation of a card acting according to ISO 7816. This +includes all standard commands for file management and secure messaging. + +Let's assume we want to create a cryptoflex card, that acts mostly according to +ISO 7816. In this example we only want to add little things that differ from +ISO 7816. But as for most complex software you need to know where you need to +hook into. Here we only want to give an overview to the design, the complete +details can be found in section `Documentation to Virtual Smart Card`_ + +Back to the cryptoflex example. :class:`VirtualICC` provides the connection to +the virtual smart card reader. It fetches an |APDU| and other requests from the +|vpcd|. In :class:`VirtualICC` an |APDU| is only a buffer that is forwarded to +the smart card OS. First we modify :class:`VirtualICC` to recognize a new type +``"cryptoflex"`` and to load :class:`CryptoflexOS`. The :class:`CardGenerator` +is used to create a file system and a |SAM| specific to the cryptoflex (we come +back to this later). + +.. literalinclude:: virtualsmartcard/VirtualSmartcard.py + :pyobject: VirtualICC.__init__ + :emphasize-lines: 20,28-29 + +Responses from our cryptoflex card look the same as for the 7816 card. But when +a command was successfull (or not) there is a little difference in what is +returned. So we need to edit :class:`CryptoflexOS.formatResult`, which is +called to encode the |SWs| and the resulting data. + +.. literalinclude:: virtualsmartcard/VirtualSmartcard.py + :pyobject: CryptoflexOS.formatResult + +Note that this also requires some insight knowledge about how +:class:`Iso7816OS` works (see `below `_). + +The previously created |SAM| handles keys, encryption, secure messaging and so +on (we will not go into more details here). The file system creates, selects +and reads contents of files or directories. File handling for our cryptoflex +card is similar to ISO 7816, but the meaning of P1, P2 and the |APDU| data is +completely different when creating a file on the smart card. So we derive +:class:`CryptoflexMF` from :class:`MF` and modify :class:`CryptoflexMF.create` +to our needs. + +.. literalinclude:: virtualsmartcard/cards/cryptoflex.py + :pyobject: CryptoflexMF.create + +As you can see it is quite simple to extend the virtual smart card to your +requirements. Simply overwrite those functions, that differ from ISO 78166. But +as said before, the virtual smart card is quite complex and you might have to +read some documentation or even source code to find out where it's best to do +your modifications... + + +=================================== +Documentation to Virtual Smart Card +=================================== + .. toctree:: api/virtualsmartcard diff --git a/virtualsmartcard/doc/virtualsmartcard b/virtualsmartcard/doc/virtualsmartcard new file mode 120000 index 0000000..0b2bc7b --- /dev/null +++ b/virtualsmartcard/doc/virtualsmartcard @@ -0,0 +1 @@ +../src/vpicc/virtualsmartcard \ No newline at end of file