/** @mainpage

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 (http://sourceforge.net/projects/openpace/).
Some fragments of the source code are on the source code of the OpenSC tools.

The included pace-tool has support for Password Authenticated Connection
Establishment (PACE). pace-tool can be used for PIN management or to encrypt
APDUs inside a secure messaging channel established with PACE.


@section i INSTALLATION

See file INSTALL.


@subsection o 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. But so far we
manually build it to have libopensc for linking. The good thing is that you
don't need any opensc components to be installed. The bad thing is, that libnpa
configures and builds opensc on its own. So you might need to pass some extra
configure options to opensc. So if you need to pass options to opensc, use
something like the following command:
./configure \
    OPENSC_CONFIGURE="options"

Worse gets the situation if you need to link against libnpa and some opensc
library at the same time. This will yield conflicts since functionality of
libopensc is linked into both libraries. This is possible (see ccid-emulator),
but not recommended. Only do this if you know what you are doing.


@subsection o 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.0c_with_openpace-0.4/include" \
    OPENSSL_LIBS="-L/path/to/openssl-1.0.0c_with_openpace-0.4 -lcrypto"


@section u USAGE

When testing PACE with either PIN, CAN, MRZ or PUK run pace-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 pace-tool, the command line parameters or the environment
variables PIN/CAN/MRZ/PUK/NEWPIN can be used. If none of these options is used,
pace-tool will show a password prompt.


@section q QUESTIONS
For questions, please use http://sourceforge.net/projects/vsmartcard/support

@author Frank Morgner <morgner@informatik.hu-berlin.de>
*/