nPA Smart Card Library¶
| Author: | Frank Morgner <morgner@informatik.hu-berlin.de> |
|---|---|
| License: | GPL version 3 |
| Tested Platforms: | |
|
|
| Potential Platforms: | |
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 is implemented using OpenPACE. Some fragments of the source code are based on the source code of the OpenSC tools.
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 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:
autoreconf -i
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:
Hints on OpenSSL with OpenPACE¶
The nPA Smart Card Library links against OpenSSL, which must be patched with OpenPACE. Here is an example of how to get the standard installation of OpenPACE:
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:
./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
Hints on OpenSC¶
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"
Usage¶
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 <morgner@informatik.hu-berlin.de>
Linking against libnpa¶
Following the section Installation above, you have installed OpenSC with PACE, OpenPACE and the nPA Smart Card Library to /tmp/install. To compile a program using nPA Smart Card Library you need to get the header files from OpenSC with PACE as well. Here is how to compile an external program with these libraries:
PREFIX=/tmp/install
OPENSC=opensc
git clone git://github.com/frankmorgner/OpenSC.git $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
git clone git://github.com/frankmorgner/OpenSC.git $OPENSC
cc example.c -I$OPENSC/src \
-I$PREFIX/include \
-L$PREFIX/lib -lcrypto -lnpa -lopensc"
Question¶
Do you have questions, suggestions or contributions? Feedback of any kind is more than welcome! Please use our project trackers.
