# Welcome to OpenPACE’s documentation!¶

OpenPACE implements Extended Access Control (EAC) version 2 as specified in BSI TR-03110 [1]. OpenPACE comprises support for the following protocols:

Establish a secure channel with a strong key between two parties that only share a weak secret.
Terminal Authentication (TA):
Verify/prove the terminal’s certificate (or rather certificate chain) and secret key.
Chip Authentication (CA):
Establish a secure channel based on the chip’s static key pair proving its authenticy.

Furthermore, OpenPACE also supports Card Verifiable Certificates (CV Certificates) as well as easy to use wrappers for using the established secure channels.

The handlers for looking up trust anchors during TA and CA (i.e. the CSCA and the CSCA certificates) can be customized. By default, the appropriate certificates will be looked up in the file system.

OpenPACE supports all variants of PACE (DH/ECDH, GM/IM), TA (RSASSA-PKCS1-v1_5/RSASSA-PSS/ECDSA), CA (DH/ECDH) and all standardized domain parameters (GFP/ECP).

OpenPACE is implemented as C-library and comes with native language wrappers for:

• Python
• Ruby
• Javascript
• Java
• Go

Note

OpenPACE only implements the cryptographic protocols of the EAC. If you actually want to exchange data with a smart card, you need to take care of formatting and sending the data in the form of APDUs. If this is what you’re trying to do, you should have a look at the npa-tool of the nPA Smart Card Library [2].

You can find the latest release of OpenPACE on Sourceforge.

Alternatively, you can clone our git repository:

git clone https://github.com/frankmorgner/openpace.git


## Install OpenPACE¶

OpenPACE uses the GNU Build System to compile and install. If you are unfamiliar with it, please have a look at INSTALL. If you can not find it, you are probably working bleeding edge in the repository. Run the following command in openpace to get the missing standard auxiliary files:

autoreconf --verbose --install


To configure (configure –help lists possible options), build and install OpenPACE now do the following:

./configure
make
make install


OpenPACE depends on the OpenSSL [3] library. Since PACE uses CMAC and the Brainpool curves, the currently unreleased version 1.0.2 of OpenSSL is required.

Furthermore, additional object identifiers from BSI TR-03110 [1] are required. You have two options to get them to work:

1. Let OpenPACE load the object identifiers at runtime
2. Patch OpenSSL to include the identifiers

The first option allows you to install an unchanged version of OpenSSL to your system. However, performance will be slightly worse and there are some limitations. For example, you won’t be able to use the new NIDs as labels in a switch statement and you need to make sure to call EAC_init() first. For patching OpenSSL we provide oids.patch. You can configure OpenPACE with --enable-openssl-install, which will automatically download, patch, build and install OpenSSL if needed.

### Cross compiling OpenPACE¶

We have added some scripts for the ease of cross compiling for Windows and Android. Both are tested with Debian wheezy. First create a working Makefile:

test -x configure || autoreconf --verbose --install
./configure


#### Compiling for Windows¶

Cross compilation for Windows can be done with:

make win

Make Variable Default Meaning
WIN_TOOL i686-w64-mingw32 cross compiler
WIN_TOOL_DIR /usr/${WIN_TOOL} root directory of the cross compiler containing the lib and include folders On successfull compilation, the Windows binaries can be found in openpace-0.9_win32. #### Compiling for Android¶ Cross compilation for Android can be done with: make android  Make Variable Default Meaning ANDROID_ARCH arm target Architecture ANDROID_TOOL${ANDROID_ARCH}-linux-androideabi cross compiler
MAKE_STANDALONE_TOOLCHAIN ${HOME}/.local/opt/android-ndk-r9/build/tools/make-standalone-toolchain.sh location of the NDK script for creating the toolchain On successfull compilation, the Android binaries can be found in openpace-0.9_$ANDROID_ARCH.

#### Compiling for Javascript¶

Technically the process for getting OpenPACE into Javascript is similar to cross compiling. With Emscripten [5] the library is compiled into LLVM bytecode and then translated into Javascript. Use the following command:

make emscripten

Make Variable Default Meaning
EMSCRIPTEN_DIR ${HOME}/.local/src/emscripten root directory of emscripten containing the system/include/libc folder On successfull compilation, the compiled bitcode files can be found in openpace-0.9_bc. You can run our testsuite completely in Javascript or in your browser: nodejs openpace-0.9_bc/eactest.js # WARNING: Our tests are very time consuming and might stall your browser for a moment or two... firefox openpace-0.9_bc/eactest.html  Warning Javascript cryptography is considered harmful [6]. You may want to think twice before using the Javascript version of OpenPACE. ## How to use OpenPACE¶ OpenPACE is a native C library on top of OpenSSL. If you want to know how to use OpenPACE from C/C++, have a look at our API documentation. OpenPACE uses SWIG [4] to offer bindings in some more programming languages. The bindings are easily portable to lots of different languages. Currently, native language bindings need to be explicitly turned on with ./configure --enable-... If you have chosen to install OpenPACE in a non-standard location you have to set up the LD_LIBRARY_PATH environment variable correctly. One way to do this is: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libeac


If OpenPACE is compiled for Javascript, it results in a standalone Javascript file that can be used without special requirements.

More details and a number of examples are covered here:

## Where to get help¶

Do you have questions, suggestions or contributions? Feedback of any kind is more than welcome! You can contact us through our GitHub repositories or the project trackers.