.. highlight:: sh

.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |TA| replace:: :abbr:`TA (Terminal Authenticatation)`
.. |CA| replace:: :abbr:`CA (Chip Authentication)`
.. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. |CVCA| replace:: :abbr:`CVCA (Country Verifying Certificate Authority)`
.. |CSCA| replace:: :abbr:`CSCA (Country Signing Certificate Authority)`

*******************************************************************************
Download @PACKAGE_NAME@
*******************************************************************************

You can download the latest release of @PACKAGE_NAME@ on `Github
<https://github.com/frankmorgner/openpace/releases/latest>`_. Older releases
are still available on `Sourceforge
<http://sourceforge.net/projects/openpace/files>`_.

Alternatively, you can clone our git repository::

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


*******************************************************************************
Install @PACKAGE_NAME@
*******************************************************************************

=======================================
Installation on Linux, Unix and similar
=======================================

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

To configure (:command:`./configure --help` lists possible options), build and
install @PACKAGE_NAME@ now do the following::

    ./configure
    make
    make install

@PACKAGE_NAME@ depends on the `OpenSSL`_ library. Since |PACE| uses CMAC and the
Brainpool curves, OpenSSL is required with version 1.0.2 or later.

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

1. Let @PACKAGE_NAME@ 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 :file:bsi_objects.txt``. You can configure
@PACKAGE_NAME@ with :option:`--enable-openssl-install`, which will
automatically download, patch, build and install OpenSSL if needed.

The language bindings for Python, Java, ... are currently disabled by default.
You need to explicitely configure @PACKAGE_NAME@ to install them by using
:option:`--enable-python`, :option:`--enable-java`, ... This requires SWIG to
be installed along with the language's toolchain to build the bindings.

==========================================================
Setting up a development or test environment using vagrant
==========================================================

The easiest way to setup a development or test environment is to use `vagrant
<https://www.vagrantup.com>`_. @PACKAGE_NAME@ comes with a Vagrantfile which
let's you setup a working environment with just one command. All you need to do
is type `vagrant up` in the @PACKAGE_NAME@ directory. vagrant then sets up a
Ubuntu based virtual machine, installs all dependencies and configures
@PACKAGE_NAME@. You then need to `vagrant ssh` in order to access the VM. The
`openpace` folder is shared between the host and the VM so any changes you
make on the host are immediately visible in the VM and vice versa. In order to
use vagrant you need to install vagrant and virtualbox. Both are available via
the repositories of most linux distributions.

===============================================================================
Cross compiling @PACKAGE_NAME@
===============================================================================

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
:file:`Makefile`::

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

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 :file:`lib` and :file:`include` folders
================ ==================== ===========================================================================================

gendef_ should be installed to generate the library definitions.
On successfull compilation, the Windows binaries can be found in
:file:`@PACKAGE_TARNAME@-@PACKAGE_VERSION@_win32`.

With these binaries you may now compile the native Python bindings. For this
you need to setup your Windows as following:

1. Check out the git repository to the directory :file:`C:\\openpace`

2. Install `Visual Studio 2013`_ and open :menuselection:`Visual Studio Tools
   --> Developer Command Prompt`

3. Install `SWIG`_ and modify the :envvar:`PATH` so that :command:`swig.exe`
   can be found::

    set PATH="C:\swig";%PATH%

4. Install `Python`_ and set :envvar:`PYTHON_INCLUDE` and
   :envvar:`PYTHON_LIBD`/:envvar:`PYTHON_LIB` accordingly::

    set PYTHON_INCLUDE="C:\Python27\include"
    set PYTHON_LIBD="C:\Python27"
    set PYTHON_LIB="python278.lib"

5. Copy the cross compiled OpenPACE libraries to Windows and set :envvar:`OPENPACE_ROOT`::
   
    set OPENPACE_ROOT="C:\openpace\openpace-1.0.0_win32

6. Create OpenPACE's and OpenSSL's import libraries::

    lib /def:"%OPENPACE_ROOT%\lib\libeac-1.def" /OUT:"%OPENPACE_ROOT%\lib\libeac.lib"
    lib /def:"%OPENPACE_ROOT%\lib\libeay32.def" /OUT:"%OPENPACE_ROOT%\lib\libeay32.lib"

6. Build the Python bindings::

    cd "C:\openpace"
    msbuild "bindings\win32\eac.sln"

   If you can successfully build the solution, you can find the python in
   :file:`%OPENPACE_ROOT%\\bindings\\win32\\Release`. Put them all together
   with the cross compiled OpenPACE library::
   
    copy "C:\openpace\bindings\win32\Release\_eac.pyd" "%OPENPACE_ROOT%\bin"
    copy "C:\openpace\bindings\win32\Release\eac.py"   "%OPENPACE_ROOT%\bin"
    copy "C:\openpace\bindings\python\chat.py"         "%OPENPACE_ROOT%\bin"
    copy "C:\openpace\bindings\python\pace_entity.py"  "%OPENPACE_ROOT%\bin"
   
   Now for testing, you may try::

    cd "%OPENPACE_ROOT%\bin"
    "%PYTHON_LIBD%\python.exe" "C:\openpace\bindings\python\example.py"

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-r10e/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
:file:`@PACKAGE_TARNAME@-@PACKAGE_VERSION@_${ANDROID_ARCH}-linux-androideabi`.

.. _javascript_api:

Compiling for Javascript
-------------------------------------------------------------------------------

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

    make emscripten

============================= ================================== ==============================================================================
Make Variable                 Default                            Meaning
============================= ================================== ==============================================================================
``EMSCRIPTEN_ROOT``           ``${HOME}/.local/src/emscripten``  root directory of emscripten containing the :file:`system/include/libc` folder
============================= ================================== ==============================================================================

On successfull compilation, the compiled bitcode files can be found in
:file:`@PACKAGE_TARNAME@-@PACKAGE_VERSION@_js`. You can run our testsuite
completely in Javascript or `in your browser <_static/eactest.html>`_::

    nodejs @PACKAGE_TARNAME@-@PACKAGE_VERSION@_js/bin/eactest.js
    firefox @PACKAGE_TARNAME@-@PACKAGE_VERSION@_js/eactest.html

.. warning::
    `Javascript cryptography is considered harmful`_. You may want to think
    twice before using the Javascript version of OpenPACE.


.. target-notes::

.. _`BSI TR-03110`: https://www.bsi.bund.de/EN/Publications/TechnicalGuidelines/TR03110/BSITR03110.html
.. _`Emscripten`: https://github.com/kripken/emscripten
.. _`Javascript cryptography is considered harmful`: http://www.matasano.com/articles/javascript-cryptography
.. _`OpenSSL`: http://openssl.org
.. _`SWIG`: http://www.swig.org/download.html
.. _`Python`: https://www.python.org/downloads/release/python-278/
.. _`gendef`: http://sourceforge.net/p/mingw-w64/wiki2/gendef/
.. _`Visual Studio 2013`: http://msdn.microsoft.com/library/dd831853.aspx
