From ebfb0236586669497367406fd554b80318deebd2 Mon Sep 17 00:00:00 2001 From: frankmorgner Date: Thu, 27 Oct 2011 15:23:06 +0000 Subject: [PATCH] documentation git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@586 96b47cad-a561-4643-ad3b-153ac7d7599c --- ccid/README.dox | 55 +++++++++++++++++++++---------------- npa/README.dox | 7 +++-- pcsc-relay/README | 17 ++++++++---- virtualsmartcard/README | 61 ++++++++++++++++++++++++++++++----------- 4 files changed, 93 insertions(+), 47 deletions(-) diff --git a/ccid/README.dox b/ccid/README.dox index 8085681..bcda317 100644 --- a/ccid/README.dox +++ b/ccid/README.dox @@ -1,6 +1,9 @@ .. highlight:: sh .. _OpenSC: http://www.opensc-project.org/opensc +.. _GadgetFS: http://www.linux-usb.org/gadget/ +.. _libccid: http://pcsclite.alioth.debian.org/ccid.html + ************* ccid-emulator @@ -21,9 +24,9 @@ reader to the host system. ccid-emulator has support for Password Authenticated Connection Establishment (PACE) using OpenPACE (http://sourceforge.net/projects/openpace/). -ccid-emulator is implemented using GadgetFS. Some fragments of the source code -are based on the GadgetFS example at http://www.linux-usb.org/gadget/ and on the -source code of the OpenSC tools. +ccid-emulator is implemented using GadgetFS_. Some fragments of the source code +are based on the GadgetFS_ example and on the source code of the OpenSC_ tools. + ============= Installation @@ -32,33 +35,36 @@ Installation ccid uses the GNU Build System to compile and install. If you are unfamiliar with it, please have a look at the 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 the npa direcotry to get the missing standard +Run the following command in the npa directory to get the missing standard auxiliary files:: - autoreconf -i + autoreconf -i ccid as the following dependencies: - - OpenSC_ - - libnpa +- Linux Kernel with GadgetFS_ +- OpenSC_ +- libnpa ------------------- -Hints of GadgetFS ------------------- + +----------------- +Hints on GadgetFS +----------------- To create an USB Gadget in both USB host and USB client mode, you need to load -the kernel module gadgetfs. A guide focused on Debian based systems to run and -compile gadgetfs, you can find here: -http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module +the kernel module ``gadgetfs``. A guide focused on Debian based systems to run +and compile gadgetfs, you can find `here +`_. -On OpenMoko it is likely that you need to patch your kernel (see -http://docs.openmoko.org/trac/ticket/2206). If you also want to switch multiple -times between gadgetfs and g_ether, another patch is needed (see -https://docs.openmoko.org/trac/ticket/2240). +On OpenMoko it is likely that you need to `patch your kernel +`_. If you also want to switch +multiple times between ``gadgetfs`` and ``g_ether``, `another patch is needed +`_. + +If you are using a more recent version of ``dummy_hcd`` and get an error +loading the module, you maybe want to check out `this patch +`_. -If you are using a more recent version of dummy_hcd, you maybe want to check -out this patch: -http://comments.gmane.org/gmane.linux.usb.general/47440 --------------- Hints on OpenSC @@ -90,15 +96,16 @@ Usage ===== ccid-emulator has various command line options to customize the appearance on -the USB host. In order to run ccid-emulator GadgetFS must be loaded and mounted. -ccid-emulator is compatible with the unix driver libccid and the windows smart -card driver. To initialize PACE using the PC/SC API you need to patch libccid -and pcsc-lite (see directory patches). +the USB host. In order to run ccid-emulator GadgetFS_ must be loaded and +mounted. ccid-emulator is compatible with the unix driver libccid_ and the +windows smart card driver. To initialize PACE using the PC/SC API you need to +patch libccid and pcsc-lite (see directory patches). cats-test can be used to test the PACE capabilities of a smart card reader with PACE support (such as ccid-emulator or any other "Standardleser" CAT-S or "Komfortleser" CAT-C) via PC/SC. + ========= Questions ========= diff --git a/npa/README.dox b/npa/README.dox index 8dbb0b8..f1ad926 100644 --- a/npa/README.dox +++ b/npa/README.dox @@ -3,11 +3,11 @@ .. _OpenSC: http://www.opensc-project.org/opensc .. _OpenPACE: http://sourceforge.net/projects/openpace/ + *** npa *** - :Author: Frank Morgner :License: @@ -26,6 +26,7 @@ The included npa-tool has support for Password Authenticated Connection Establishment (PACE). npa-tool can be used for PIN management or to encrypt APDUs inside a secure messaging channel established with PACE. + .. _npa-install: ============ @@ -35,7 +36,7 @@ Installation npa uses the GNU Build System to compile and install. If you are unfamiliar with it, please have a look at the 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 the npa direcotry to get the missing standard +Run the following command in the npa directory to get the missing standard auxiliary files:: autoreconf -i @@ -45,6 +46,7 @@ npa has the following dependencies: - OpenSC_ - OpenSSL with OpenPACE_ + ------------------------------ Hints on OpenSSL with OpenPACE ------------------------------ @@ -69,6 +71,7 @@ to configure npa to use it:: ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig + --------------- Hints on OpenSC --------------- diff --git a/pcsc-relay/README b/pcsc-relay/README index 30b5f5c..06775bb 100644 --- a/pcsc-relay/README +++ b/pcsc-relay/README @@ -3,14 +3,18 @@ .. _libnfc: http://www.libnfc.org/ .. _PCSC-lite: http://pcsclite.alioth.debian.org/ + ********** pcsc-relay ********** -.. Authors : Dominik Oepen -.. Frank Morgner -.. License : See file COPYING -.. Tested Platforms : Linux 2.6 (Debian, Ubuntu, Om 2008) +:Authors: + - Dominik Oepen + - Frank Morgner +:License: + GPL version 3 +:Tested Platforms: + Linux (Debian, Ubuntu, OpenMoko) Welcome to pcsc-relay. The purpose of pcsc-relay is to forward APDUs from the OpenPICC or from a libnfc device to a smart card via the PCSC middleware. You @@ -25,7 +29,7 @@ Installation pcsc-relay uses the GNU Build System to compile and install. If you are unfamiliar with it, please have a look at the 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 the pcsc-relay direcotry to get the +repository. Run the following command in the pcsc-relay directory to get the missing standard auxiliary files:: autoreconf -i @@ -35,6 +39,7 @@ pcsc-relay has the following dependencies: - PC/SC middleware - libnfc_ + --------------- Hints on libnfc --------------- @@ -57,6 +62,7 @@ configure pcsc-relay to use it:: ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig + ------------------------- Hints on PC/SC middleware ------------------------- @@ -68,6 +74,7 @@ distribution. Windows also ships with a PC/SC middleware in form of the Winscard module. Microsoft's developement environment Visual Studio includes all necessary data for building pcsc-relay. + ========= Questions ========= diff --git a/virtualsmartcard/README b/virtualsmartcard/README index ae61df1..4dd3430 100644 --- a/virtualsmartcard/README +++ b/virtualsmartcard/README @@ -1,3 +1,15 @@ +.. highlight:: sh + +.. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/ +.. _PCSC-lite: http://pcsclite.alioth.debian.org/ +.. _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 +.. _pyscard: http://pyscard.sourceforge.net/ + + ****************** Virtual Smart Card ****************** @@ -16,38 +28,55 @@ smart card and make it accessible through PCSC. Currently the virtual smart card supports almost all commands of ISO-7816 including secure messaging. Besides a plain ISO-7816 smart card it is also possible to emulate a German ePass (only basic access control) and a rudimentary Cryptoflex smart card. The -virtual smart card can be accessed through the virtual smart card reader which -is a driver for pcscd of PCSC-Lite. +virtual smart card (vpicc) can be accessed through the virtual smart card +reader (vpcd) which is a driver for ``pcscd`` of PCSC-Lite_. -By default the virtual smart card communicates with the virtual smart card -reader through a socket on localhost port 35963. The file utils.py was taken -from `Henryk Plötz's cyberflex-shell `_. +By default the vicc communicates with the vpcd through a socket on localhost +port 35963. The file ``utils.py`` was taken from Henryk Plötz's +cyberflex-shell_. +------------ Installation ------------ -:: - autoconf -vsi - ./configure - make - make install +virtualsmartcard uses the GNU Build System to compile and install. If you are +unfamiliar with it, please have a look at the 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 the virtualsmartcard directory to get +the missing standard auxiliary files:: + + autoreconf -i + +Depending on your usage of the vpicc you might or might not need +the following: + +- Python_ +- pyscard_ +- PyCrypto_ +- PBKDF2_ +- PIP_ + +The vpcd has the following dependencies: + +- PCSC-Lite_ +------------------------ Running virtualsmartcard ------------------------ -First you need to make sure that pcscd loads the virtual smart card driver. You -might run ``update-reader.conf`` to update pcscd's configuration file. Then -``pcscd -f -d`` should say something like -readerfactory.c:1024:RFInitializeReader() Attempting startup of Virtual PCD 00 00 using /usr/lib/pcsc/drivers/serial/libvpcd.so +First you need to make sure that pcscd loads the vpcd. You might need to run +``update-reader.conf`` to update pcscd's configuration file. Then ``pcscd -f +-d`` should say something like ``Attempting startup of Virtual PCD`` Now you can run ``vicc`` which connects to the virtual reader. The command ``vicc --help`` gives an overview about the command line options. -You should now be able to access the virtual smart card through the system's -PC/SC API. You can use the opensc-explorer or pcsc_scan to test that. +You should now be able to access the vpicc through the system's +PC/SC API via vpcd/pcscd. You can use the opensc-explorer or pcsc_scan to test +that. Question