Frank Morgner <firstname.lastname@example.org>
GPL version 3
Unix-like operating systems (Mac OS, Solaris, BSD, ...)
The nPA Smart Card Library offers 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 included npa-tool can be used for PIN management or to send APDUs inside a secure channel.
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 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 npa to get the missing standard auxiliary files:
To configure (configure –help lists possible options), build and install the nPA Smart Card Library now do the following:
./configure make make install
The nPA Smart Card Library has the following dependencies:
PREFIX=/tmp/install OPENPACE=openpace svn co https://openpace.svn.sourceforge.net/svnroot/openpace $OPENPACE cd $OPENPACE make patch_with_openpace cd openpace ./config experimental-pace --prefix=$PREFIX make depend make make install
Building the nPA Smart Card Library with OpenPACE is done best using pkg-config. The file libcrypto.pc should be located in $INSTALL/lib/pkgconfig. Here is how to configure the nPA Smart Card Library to use it:
The nPA Smart Card Library links against OpenSC, which is discouraged and hindered since OpenSC version >= 0.12. However, I extended OpenSC to support smart card readers with PACE capabilities. You need the OpenSC components to be installed (especially libopensc.so). Here is an example of how to get the standard installation of OpenSC with PACE:
PREFIX=/tmp/install OPENSC=opensc git clone git://github.com/frankmorgner/OpenSC.git $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 the nPA Smart Card Library to use it:
./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc"
To pass a secret to npa-tool for PACE, command line parameters or environment variables can be used. If the smart card reader supports PACE, the PIN pad is used. If none of these options is applies, npa-tool will show a password prompt.
npa-tool can send arbitrary APDUs to the nPA in the secure channel. APDUs are entered interactively or through a file. APDUs are formatted in hex (upper or lower case) with an optional colon to separate the bytes. Example APDUs can be found in apdus.
npa-tool 0.5 Access the German electronic identity card (neuer Personalausweis, nPA) Usage: npa-tool [OPTIONS]... -h, --help Print help and exit -V, --version Print version and exit -i, --info Print available readers and drivers. (default=off) -r, --reader=INT Number of the PC/SC reader to use (-1 for autodetect) (default=`-1') -v, --verbose Use (several times) to be more verbose --env Whether to use environment variables PIN, PUK, CAN, MRZ and NEWPIN. You may want to clean your environment before enabling this. (default=off) Secrets for establishing the secure PACE channel to the card: -p, --pin[=STRING] Run PACE with (transport) eID-PIN -u, --puk[=STRING] Run PACE with PUK -c, --can[=STRING] Run PACE with CAN -m, --mrz[=STRING] Run PACE with MRZ (insert MRZ without newlines) PIN management: -N, --new-pin=STRING Install a new PIN -R, --resume Resume eID-PIN (uses CAN to activate last retry) (default=off) -U, --unblock Unblock PIN (uses PUK to activate three more retries) (default=off) Special options, not always useful: -b, --break Brute force PIN, CAN or PUK (default=off) --chat=HEX_STRING Card holder authorization template to use --cert-desc=HEX_STRING Certificate description to use for Terminal Authentication -t, --translate=FILENAME File with APDUs to send through the secure channel (default=`stdin') --tr-03110v201 Force compliance to BSI TR-03110 version 2.01 (default=off) Report bugs to http://sourceforge.net/projects/vsmartcard/support Written by Frank Morgner <email@example.com>