VivoKey/vsmartcard
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

working on documentation

Browse Source
This commit is contained in:
Frank Morgner
2013-05-13 08:15:05 +02:00
parent ae8c086606
commit 54579ae7d7
25 changed files with 305 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
virtualsmartcard/doc/Makefile.am
View File

@@ -17,7 +17,7 @@ do_subst = $(SED) \
-e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \
-e 's,[@]top_srcdir[@],$(top_srcdir),g'
EXTRA_DIST = README.txt.in README.txt autotools.txt.in questions.txt.in autotools.txt questions.txt download.txt.in download.txt
EXTRA_DIST = README.txt.in README.txt autotools.txt.in questions.txt.in autotools.txt questions.txt download.txt.in download.txt relay-note.txt
dist_noinst_SCRIPTS = generate_modules.py

35
virtualsmartcard/doc/README.txt
View File

@@ -2,21 +2,21 @@
.. |vpicc| replace:: :abbr:`vpicc (virtual smart card)`
.. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)`
.. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. |BAC| replace:: :abbr:`BAC (Basic Access Control)`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |TA| replace:: :abbr:`TA (Terminal Authenticatation)`
.. |CA| replace:: :abbr:`CA (Chip Authentication)`
.. |BAC| replace:: :abbr:`BAC (Basic Access Control)`
.. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. _vicc:
##################
################################################################################
Virtual Smart Card
##################
################################################################################
:Authors:
- Frank Morgner <morgner@informatik.hu-berlin.de>
- Dominik Oepen <oepen@informatik.hu-berlin.de>
- `Frank Morgner <morgner@informatik.hu-berlin.de>`_
- `Dominik Oepen <oepen@informatik.hu-berlin.de>`_
:License:
GPL version 3
:Tested Platforms:
@@ -46,6 +46,9 @@ reader.
The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_.
.. include:: relay-note.txt
.. include:: download.txt
@@ -59,13 +62,14 @@ the following:
- PyCrypto_
- PBKDF2_
- PIP_
- OpenPACE_ (nPA emulation)
The |vpcd| depends on PCSC-Lite_.
******************************
********************************************************************************
Running the Virtual Smart Card
******************************
********************************************************************************
Fitxt you need to make sure that :command:`pcscd` loads the |vpcd|. You might
need to run :command:`update-reader.conf` to update its configuration file.
@@ -82,9 +86,9 @@ You should now be able to access the |vpicc| through the PC/SC API via
:command:`pcsc_scan` for testing.
==========================================================
================================================================================
Accessing the Virtual Smart Card from Windows applications
==========================================================
================================================================================
Running |vpcd| under Windows is currently not supported, because it implements
a smart card driver specific for PCSC-Lite (:command:`pcscd`). This means, that
@@ -121,10 +125,11 @@ Notes and References
.. target-notes::
.. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/
.. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _PIP: http://www.pythonware.com/products/pil/
.. _PyCrypto: http://pycrypto.org/
.. _Python: http://www.python.org/
.. _cyberflex-shell: https://github.com/henryk/cyberflex-shell
.. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _Python: http://www.python.org/
.. _pyscard: http://pyscard.sourceforge.net/
.. _PyCrypto: http://pycrypto.org/
.. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/
.. _PIP: http://www.pythonware.com/products/pil/
.. _OpenPACE: http://openpace.sourceforge.net

47
virtualsmartcard/doc/README.txt.in
View File

@@ -2,21 +2,21 @@
.. |vpicc| replace:: :abbr:`vpicc (virtual smart card)`
.. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)`
.. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. |BAC| replace:: :abbr:`BAC (Basic Access Control)`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |TA| replace:: :abbr:`TA (Terminal Authenticatation)`
.. |CA| replace:: :abbr:`CA (Chip Authentication)`
.. |BAC| replace:: :abbr:`BAC (Basic Access Control)`
.. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. _vicc:
##################
Virtual Smart Card
##################
################################################################################
@PACKAGE_NAME@
################################################################################
:Authors:
- Frank Morgner <morgner@informatik.hu-berlin.de>
- Dominik Oepen <oepen@informatik.hu-berlin.de>
- `Frank Morgner <morgner@informatik.hu-berlin.de>`_
- `Dominik Oepen <oepen@informatik.hu-berlin.de>`_
:License:
GPL version 3
:Tested Platforms:
@@ -25,8 +25,8 @@ Virtual Smart Card
:Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...)
Virtual Smart Card emulates a smart card and makes it accessible through PC/SC.
Currently the Virtual Smart Card supports the following types of smart cards:
@PACKAGE_NAME@ emulates a smart card and makes it accessible through PC/SC.
Currently the @PACKAGE_NAME@ supports the following types of smart cards:
- Generic ISO-7816 smart card including secure messaging
- German electronic identity card (nPA) with complete support for |EAC| (|PACE|, |TA|, |CA|)
@@ -39,13 +39,16 @@ default |vpicc| communicates with |vpcd| through a socket on localhost port
35963. But the |vpicc| does not need to run on the same machine as the |vpcd|,
they can connect over the internet for example.
Although the Virtual Smart Card is a software emulator, you can use
Although the @PACKAGE_NAME@ is a software emulator, you can use
:ref:`pcsc-relay` to make it accessible to an external contact-less smart card
reader.
The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_.
.. include:: relay-note.txt
.. include:: download.txt
@@ -59,13 +62,14 @@ the following:
- PyCrypto_
- PBKDF2_
- PIP_
- OpenPACE_ (nPA emulation)
The |vpcd| depends on PCSC-Lite_.
******************************
Running the Virtual Smart Card
******************************
********************************************************************************
Running the @PACKAGE_NAME@
********************************************************************************
Fitxt you need to make sure that :command:`pcscd` loads the |vpcd|. You might
need to run :command:`update-reader.conf` to update its configuration file.
@@ -82,9 +86,9 @@ You should now be able to access the |vpicc| through the PC/SC API via
:command:`pcsc_scan` for testing.
==========================================================
Accessing the Virtual Smart Card from Windows applications
==========================================================
================================================================================
Accessing the @PACKAGE_NAME@ from Windows applications
================================================================================
Running |vpcd| under Windows is currently not supported, because it implements
a smart card driver specific for PCSC-Lite (:command:`pcscd`). This means, that
@@ -121,10 +125,11 @@ Notes and References
.. target-notes::
.. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/
.. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _PIP: http://www.pythonware.com/products/pil/
.. _PyCrypto: http://pycrypto.org/
.. _Python: http://www.python.org/
.. _cyberflex-shell: https://github.com/henryk/cyberflex-shell
.. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _Python: http://www.python.org/
.. _pyscard: http://pyscard.sourceforge.net/
.. _PyCrypto: http://pycrypto.org/
.. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/
.. _PIP: http://www.pythonware.com/products/pil/
.. _OpenPACE: http://openpace.sourceforge.net

33
virtualsmartcard/doc/api.txt
View File

@@ -58,14 +58,14 @@ 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:`virtualsmartcard.VirtualSmartcard.VirtualICC` provides the connection
:class:`~virtualsmartcard.VirtualSmartcard.VirtualICC` provides the connection
to the virtual smart card reader. It fetches an |APDU| and other requests from
the |vpcd|. In :class:`virtualsmartcard.VirtualSmartcard.VirtualICC` an |APDU|
the |vpcd|. In :class:`~virtualsmartcard.VirtualSmartcard.VirtualICC` an |APDU|
is only a buffer that is forwarded to the smart card OS. First we modify
:class:`virtualsmartcard.VirtualSmartcard.VirtualICC` to recognize a new type
:class:`~virtualsmartcard.VirtualSmartcard.VirtualICC` to recognize a new type
``"cryptoflex"`` and to load
:class:`virtualsmartcard.VirtualSmartcard.CryptoflexOS`. The
:class:`virtualsmartcard.CardGenerator` is used to create a file system and a
:class:`~virtualsmartcard.VirtualSmartcard.CryptoflexOS`. The
:class:`~virtualsmartcard.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
@@ -75,14 +75,14 @@ is only a buffer that is forwarded to the smart card OS. First we modify
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:`virtualsmartcard.VirtualSmartcard.CryptoflexOS.formatResult`, which is
:class:`~virtualsmartcard.VirtualSmartcard.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:`virtualsmartcard.VirtualSmartcard.Iso7816OS` works (see `above
:class:`~virtualsmartcard.VirtualSmartcard.Iso7816OS` works (see `above
<Documentation to Virtual Smart Card>`_).
The previously created |SAM| handles keys, encryption, secure messaging and so
@@ -90,9 +90,9 @@ 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:`virtualsmartcard.cards.cryptoflex.CryptoflexMF` from
:class:`virtualsmartcard.SmartcardFilesystem.MF` and modify
:class:`virtualsmartcard.cards.cryptoflex.CryptoflexMF.create` to our needs.
:class:`~virtualsmartcard.cards.cryptoflex.CryptoflexMF` from
:class:`~virtualsmartcard.SmartcardFilesystem.MF` and modify
:class:`~virtualsmartcard.cards.cryptoflex.CryptoflexMF.create` to our needs.
.. literalinclude:: virtualsmartcard/cards/cryptoflex.py
:pyobject: CryptoflexMF.create
@@ -112,18 +112,11 @@ If you have a card entirely different to ISO 7816, you surely want to avoid all
magic that is done while parsing a buffer (an |APDU|). As example we will
connect to an other smart card using PC/SC and forward it to |vpcd|.
.. note::
This software can actually be used in a relay attack allowing full access
to the card... `We discussed the impact especially on the German identity
card
<http://media.ccc.de/browse/congress/2010/27c3-4297-de-die_gesamte_technik_ist_sicher.html>`_,
but it generally concerns *all smart cards*.
As before with the cryptoflex card, we let
:class:`virtualsmartcard.VirtualSmartcard.VirtualICC` recognize the new type
``"relay"``. :class:`virtualsmartcard.VirtualSmartcard.RelayOS` overwrites all
:class:`~virtualsmartcard.VirtualSmartcard.VirtualICC` recognize the new type
``"relay"``. :class:`~virtualsmartcard.VirtualSmartcard.RelayOS` overwrites all
main functions from the template
:class:`virtualsmartcard.VirtualSmartcard.SmartcardOS`. Its functions correspond
:class:`~virtualsmartcard.VirtualSmartcard.SmartcardOS`. Its functions correspond
to the :ref:`commands sent by vpcd <vpcd-commands>`. If you know how to use
`pyscard <http://pyscard.sourceforge.net/>`_ then the rest is pretty straight
forward, but see yourself...

8
virtualsmartcard/doc/autotools.txt
View File

@@ -5,10 +5,10 @@ Installation
************
The Virtual Smart Card uses the GNU Build System to compile and install. If you are
unfamiliar with it, please have a look at :file:`INSTALL`. If you have a look
around and can not find it, you are probably working bleeding edge in the
repository. Run the following command in :file:`virtualsmartcard` to
get the missing standard auxiliary files::
unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
it, you are probably working bleeding edge in the repository. Run the
following command in :file:`virtualsmartcard` to get the missing standard
auxiliary files::
autoreconf --verbose --install

2
virtualsmartcard/doc/download.txt
View File

@@ -4,7 +4,7 @@
Download
********
You can find the latest release of Virtual Smart Card `here
You can find the latest release of Virtual Smart Card on `Sourceforge
<http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository::

1
virtualsmartcard/doc/relay-note.txt Symbolic link
View File

@@ -0,0 +1 @@
../../pcsc-relay/doc/relay-note.txt