.. highlight:: c
.. _OpenSC: http://www.opensc-project.org/opensc
.. _OpenPACE: http://sourceforge.net/projects/openpace/
***
npa
***
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.
============
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
auxiliary files::
autoreconf -i
npa has the following dependencies:
- OpenSC_
- OpenSSL with OpenPACE_
---------------
Hints on OpenSC
---------------
libnpa links against libopensc, which is discouraged and hindered since
opensc>=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_::
OPENSC=opensc
INSTALL=/tmp/install
svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC
cd $OPENSC
autoreconf -i
./configure --prefix=$INSTALL
make
make install
Now libopensc.so should be located in $INSTALL/lib. Here is how to configure
npa to use it::
./configure OPENSC_LIBS="-L$INSTALL/lib -lopensc"
----------------
Hints on OpenSSL
----------------
If you have a local build of OpenSSL with OpenPACE_, that you want to link
against use something like the following command: ::
./configure \
OPENSSL_CFLAGS="-I/path/to/openssl-1.0.0d_with_openpace-0.6/include" \
OPENSSL_LIBS="-L/path/to/openssl-1.0.0d_with_openpace-0.6 -lcrypto"
.. _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
----------------------
If you have a local build of libnpa and OpenPACE_, the preferred way to adjust
libraries and cflags for foreign code is to use pkg-config:
``./configure PKG_CONFIG_PATH="/path/to/openssl-1.0.0d_with_openpace-0.6/lib/pkgconfig:/path/to/libnpa/lib/pkgconfig"``
Alternatively you can define libs and cflags by hand: ::
./configure \
OPENSSL_CFLAGS="-I/path/to/openssl-1.0.0d_with_openpace-0.6/include" \
LIBNPA_CFLAGS="-I/path/to/openssl-1.0.0d_with_openpace-0.6/include -I/path/to/libnpa-0.1/src" \
OPENSSL_LIBS="-L/path/to/openssl-1.0.0d_with_openpace-0.6 -lcrypto" \
LIBNPA_LIBS="-L/path/to/openssl-1.0.0d_with_openpace-0.6 -lcrypto -L/path/to/libnpa-0.1/src/.libs -lnpa"
=========
Questions
=========
For questions, please use http://sourceforge.net/projects/vsmartcard/support
.. @author Frank Morgner <morgner@informatik.hu-berlin.de>
fe10d79556