diff --git a/ccid/doc/README.rst b/ccid/doc/README.rst new file mode 100644 index 0000000..cf440a2 --- /dev/null +++ b/ccid/doc/README.rst @@ -0,0 +1,99 @@ +.. 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 +******************************************************************************** + +:Author: + Frank Morgner +:License: + GPL version 3 +:Tested Platforms: + Linux (Debian, Ubuntu, OpenMoko) + +Welcome to the CCID Emulator. The purpose of the CCID Emulator is to forward a PCSC +smartcard reader as a standard USB CCID reader. If the host system is in USB +device mode, the CCID Emulator forwards the local reader via USB to another +device. If in USB host mode, the CCID Emulator virtually plugges in a USB CCID +reader to the host system. the CCID Emulator has support for Password +Authenticated Connection Establishment (PACE) using OpenPACE +(http://sourceforge.net/projects/openpace/). + +The 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. + + +.. include:: autotools.rst + +The CCID Emulator following dependencies: + +- Linux Kernel with GadgetFS_ +- OpenSC_ +- :ref:`npa` (only if support for PACE is enabled) + + +----------------- +Hints on GadgetFS +----------------- + +To create an USB Gadget in both USB host and USB client mode, you need to load +the kernel module :program:`gadgetfs`. A guide focused on Debian based systems to run +and compile :program:`gadgetfs`, you can find `here +`_. + +On OpenMoko it is likely that you need to `patch your kernel +`_. If you also want to switch +multiple times between :program:`gadgetfs` and :program:`g_ether`, `another patch is needed +`_. + +If you are using a more recent version of :program:`dummy_hcd` and get an error +loading the module, you maybe want to check out `this patch +`_. + + +--------------- +Hints on OpenSC +--------------- + +Without :ref:`npa` the CCID Emulator links against libopensc, which is discouraged and hindered since OpenSC +version >= 0.12. (We really need to get rid of this dependency or integrate +better into the OpenSC-framework.) You need the OpenSC components to be +installed (especially :file:`libopensc.so`). Here is an example of how to get the +standard installation of OpenSC_:: + + PREFIX=/tmp/install + OPENSC=opensc + svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC + cd $OPENSC + autoreconf -i + ./configure --prefix=$PREFIX + make + make install + +Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to +configure the CCID Emulator to use it:: + + ./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc" + + +===== +Usage +===== + +The CCID Emulator has various command line options to customize the appearance on +the USB host. In order to run the CCID Emulator GadgetFS_ must be loaded and +mounted. The 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 the CCID Emulator or any other "Standardleser" CAT-S or +"Komfortleser" CAT-C) via PC/SC. + + +.. include:: questions.rst diff --git a/ccid/doc/autotools.rst b/ccid/doc/autotools.rst new file mode 100644 index 0000000..c58fa43 --- /dev/null +++ b/ccid/doc/autotools.rst @@ -0,0 +1,20 @@ +.. highlight:: sh + +============= +Installation +============= + +The CCID Emulator 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:`ccid-emulator` to +get the missing standard auxiliary files:: + + autoreconf -i + +To configure (:command:`configure --help` lists possible options), build and +install the CCID Emulator now do the following:: + + ./configure + make + make install diff --git a/ccid/doc/questions.rst b/ccid/doc/questions.rst new file mode 100644 index 0000000..7c84052 --- /dev/null +++ b/ccid/doc/questions.rst @@ -0,0 +1,6 @@ +======== +Question +======== + +Do you have questions, suggestions or contributions? Feedback of any kind is +more than welcome! Please use our `project trackers `_. diff --git a/npa/doc/README.rst b/npa/doc/README.rst new file mode 100644 index 0000000..4e6a0ff --- /dev/null +++ b/npa/doc/README.rst @@ -0,0 +1,139 @@ +.. highlight:: sh + +.. _OpenSC: http://www.opensc-project.org/opensc +.. _OpenPACE: http://sourceforge.net/projects/openpace/ + + +.. _npa: + +******************************************************************************** +nPA smart card library +******************************************************************************** + +:Author: + Frank Morgner +:License: + GPL version 3 +:Tested Platforms: + Linux (Debian, Ubuntu, OpenMoko) +:Potential Platforms: + - Windows + - Unix-like operating systems (Mac OS, Solaris, BSD, ...) + +Welcome to the nPA smart card library. The purpose of the nPA smart card library is to offer an easy to use API for the new +German identity card (neuer Personalausweis, nPA). The library also implements +secure messaging, which could also be used for other cards. + +The nPA smart card library is implemented using OpenPACE_. +Some fragments of the source code are based on the source code of the OpenSC tools. + +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: + +.. include:: autotools.rst + +The nPA smart card library has the following dependencies: + +- OpenSC_ +- OpenSSL with OpenPACE_ + + +------------------------------ +Hints on OpenSSL with OpenPACE +------------------------------ + +libnpa links against libcrypto, which must be patched with OpenPACE_. Here is +an example of how to get the standard installation of OpenSSL with OpenPACE_:: + + PREFIX=/tmp/install + OPENPACE=openpace + svn co https://openpace.svn.sourceforge.net/svnroot/openpace $OPENPACE + cd $OPENPACE + make patch_with_openpace + cd openssl-*/ + ./config experimental-pace --prefix=$PREFIX + make depend + make + make install + +Building the nPA smart card library with OpenPACE_ is done best using :command:`pkg-config`. The file +:file:`libcrypto.pc` should be located in ``$INSTALL/lib/pkgconfig``. Here is how +to configure the nPA smart card library to use it:: + + ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig + + +--------------- +Hints on OpenSC +--------------- + +libnpa links against libopensc, which is discouraged and hindered since OpenSC +version >= 0.12. (We really need to get rid of this dependency or integrate +better into the OpenSC-framework.) You need the OpenSC components to be +installed (especially :file:`libopensc.so`). Here is an example of how to get the +standard installation of OpenSC_:: + + PREFIX=/tmp/install + OPENSC=opensc + svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC + cd $OPENSC + autoreconf -i + # adding PKG_CONFIG_PATH here lets OpenSC use OpenSSL with OpenPACE + ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig + make + make install + +Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to +configure the nPA smart card library to use it:: + + ./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc" + + +.. _npa-usage: + +===== +Usage +===== + +When testing PACE with either PIN, CAN, MRZ or PUK run npa-tool. Here you can +enter APDUs which are to be converted according to the secure messaging +parameter and to be sent to the card. Herefor insert the APDU in hex (upper or +lower case) with a colon to separate the bytes or without it. Example APDUs can +be found in the file apdus. + +To pass a secret to npa-tool, the command line parameters or the environment +variables PIN/CAN/MRZ/PUK/NEWPIN can be used. If none of these options is used, +npa-tool will show a password prompt. + +---------------------- +Linking against libnpa +---------------------- + +Following the section `Installation`_ above, you have installed OpenSC_, +OpenPACE_ and the nPA smart card library to :file:`/tmp/install`. To compile a program using libnpa you +need to get the header files from OpenSC_ as well. +Here is how +to compile an external program with these libraries:: + + PREFIX=/tmp/install + OPENSC=opensc + svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC + cc example.c -I$OPENSC/src \ + $(env PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig \ + pkg-config --cflags --libs npa) + +Alternatively you can specify libraries and flags by hand:: + + PREFIX=/tmp/install + OPENSC=opensc + svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC + cc example.c -I$OPENSC/src \ + -I$PREFIX/include \ + -L$PREFIX/lib -lcrypto -lnpa -lopensc" + + +.. include:: questions.rst diff --git a/npa/doc/autotools.rst b/npa/doc/autotools.rst new file mode 100644 index 0000000..6d131b1 --- /dev/null +++ b/npa/doc/autotools.rst @@ -0,0 +1,20 @@ +.. highlight:: sh + +============= +Installation +============= + +The nPA smart card library 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:`npa` to +get the missing standard auxiliary files:: + + autoreconf -i + +To configure (:command:`configure --help` lists possible options), build and +install the nPA smart card library now do the following:: + + ./configure + make + make install diff --git a/npa/doc/questions.rst b/npa/doc/questions.rst new file mode 100644 index 0000000..7c84052 --- /dev/null +++ b/npa/doc/questions.rst @@ -0,0 +1,6 @@ +======== +Question +======== + +Do you have questions, suggestions or contributions? Feedback of any kind is +more than welcome! Please use our `project trackers `_. diff --git a/pcsc-relay/doc/README.rst b/pcsc-relay/doc/README.rst new file mode 100644 index 0000000..35a2b53 --- /dev/null +++ b/pcsc-relay/doc/README.rst @@ -0,0 +1,71 @@ +.. highlight:: sh + +.. _libnfc: http://www.libnfc.org/ +.. _PCSC-lite: http://pcsclite.alioth.debian.org/ + + +******************************************************************************** +pcsc-relay +******************************************************************************** + +:Authors: + - Dominik Oepen + - Frank Morgner +:License: + GPL version 3 +:Tested Platforms: + Linux (Debian, Ubuntu, OpenMoko) +:Potential Platforms: + - Windows + - Unix-like operating systems (Mac OS, Solaris, BSD, ...) + +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 +can use this program in combination with the virtual smart card to emulate a +ISO/IEC 14443 smart card. + + +.. include:: autotools.rst + +pcsc-relay has the following dependencies: + +- PC/SC middleware +- libnfc_ + + +--------------- +Hints on libnfc +--------------- + +pcsc-relay links against libnfc_. Here is an example of how to get the standard +installation of the latter:: + + PREFIX=/tmp/install + LIBNFC=libnfc + svn co http://libnfc.googlecode.com/svn/trunk $LIBNFC + cd $LIBNFC + autoreconf -i + ./configure --prefix=$PREFIX + make + make install + +Building pcsc-relay with libnfc_ is done best using :command:`pkg-config`. The file +:file:`libnfc.pc` should be located in ``$INSTALL/lib/pkgconfig``. Here is how to +configure pcsc-relay to use it:: + + ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig + + +------------------------- +Hints on PC/SC middleware +------------------------- + +PC/SC is included by default in most modern operating systems. On Unix-like +systems (Linux, OS X, Sun OS) it is realized by PCSC-Lite_. To compile +pcsc-relay you will need to install the PCSC-Lite headers from your +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. + + +.. include:: questions.rst diff --git a/pcsc-relay/doc/autotools.rst b/pcsc-relay/doc/autotools.rst new file mode 100644 index 0000000..5ecbbff --- /dev/null +++ b/pcsc-relay/doc/autotools.rst @@ -0,0 +1,20 @@ +.. highlight:: sh + +============= +Installation +============= + +The pcsc-relay 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:`pcsc-relay` to +get the missing standard auxiliary files:: + + autoreconf -i + +To configure (:command:`configure --help` lists possible options), build and +install the pcsc-relay now do the following:: + + ./configure + make + make install diff --git a/pcsc-relay/doc/questions.rst b/pcsc-relay/doc/questions.rst new file mode 100644 index 0000000..7c84052 --- /dev/null +++ b/pcsc-relay/doc/questions.rst @@ -0,0 +1,6 @@ +======== +Question +======== + +Do you have questions, suggestions or contributions? Feedback of any kind is +more than welcome! Please use our `project trackers `_. diff --git a/virtualsmartcard/doc/README.rst b/virtualsmartcard/doc/README.rst new file mode 100644 index 0000000..4dbc2aa --- /dev/null +++ b/virtualsmartcard/doc/README.rst @@ -0,0 +1,77 @@ +.. 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/ + +.. |vpicc| replace:: :abbr:`vpicc (virtual smart card)` +.. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)` + + +******************************************************************************** +Virtual Smart Card +******************************************************************************** + +:Authors: + - Frank Morgner + - Dominik Oepen +:License: + GPL version 3 +:Tested Platforms: + - Linux (Debian, Ubuntu, OpenMoko) + - Windows (only |vpicc|, not |vpcd|) +:Potential Platforms: + Unix-like operating systems (Mac OS, Solaris, BSD, ...) + +Welcome to the Virtual Smart Card. The purpose of the Virtual Smart Card is to emulate a +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 +|vpicc| can be accessed through the |vpcd| which is a driver for +:command:`pcscd` of PCSC-Lite_. + +By default the vicc communicates with the vpcd through a socket on localhost +port 35963. The file :file:`utils.py` was taken from Henryk Plötz's +cyberflex-shell_. + + +.. include:: autotools.rst + +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 the Virtual Smart Card +================================================================================ + +First you need to make sure that pcscd loads the |vpcd|. You might need to run +:command:`update-reader.conf` to update pcscd's configuration file. Then +:command:`pcscd -f -d` should say something like "Attempting startup of +Virtual PCD" + +Now you can run :command:`vicc` which connects to the |vpcd|. The command +:command:`vicc --help` gives an overview about the command line options. + +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. + + +.. include:: questions.rst diff --git a/virtualsmartcard/doc/autotools.rst b/virtualsmartcard/doc/autotools.rst new file mode 100644 index 0000000..9007ecd --- /dev/null +++ b/virtualsmartcard/doc/autotools.rst @@ -0,0 +1,20 @@ +.. highlight:: sh + +============= +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:: + + autoreconf -i + +To configure (:command:`configure --help` lists possible options), build and +install the Virtual Smart Card now do the following:: + + ./configure + make + make install diff --git a/virtualsmartcard/doc/questions.rst b/virtualsmartcard/doc/questions.rst new file mode 100644 index 0000000..7c84052 --- /dev/null +++ b/virtualsmartcard/doc/questions.rst @@ -0,0 +1,6 @@ +======== +Question +======== + +Do you have questions, suggestions or contributions? Feedback of any kind is +more than welcome! Please use our `project trackers `_.