ef367778a4
git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@587 96b47cad-a561-4643-ad3b-153ac7d7599c
149 lines
4.4 KiB
ReStructuredText
149 lines
4.4 KiB
ReStructuredText
.. highlight:: sh
|
|
|
|
.. _OpenSC: http://www.opensc-project.org/opensc
|
|
.. _OpenPACE: http://sourceforge.net/projects/openpace/
|
|
|
|
|
|
***
|
|
npa
|
|
***
|
|
|
|
:Author:
|
|
Frank Morgner <morgner@informatik.hu-berlin.de>
|
|
:License:
|
|
GPL version 3
|
|
:Tested Platforms:
|
|
Linux (Debian, Ubuntu, OpenMoko)
|
|
|
|
Welcome to npa. The purpose of npa 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.
|
|
|
|
npa 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:
|
|
|
|
============
|
|
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 directory to get the missing standard
|
|
auxiliary files::
|
|
|
|
autoreconf -i
|
|
|
|
npa 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 npa with OpenPACE_ is done best using ``pkg-config``. The file
|
|
``libcrypto.pc`` should be located in ``$INSTALL/lib/pkgconfig``. Here is how
|
|
to configure npa 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 ``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 ``libopensc.so`` should be located in ``$PREFIX/lib``. Here is how to
|
|
configure npa 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 npa to ``/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"
|
|
|
|
=========
|
|
Questions
|
|
=========
|
|
|
|
For questions, please use http://sourceforge.net/projects/vsmartcard/support
|
|
|
|
|