Common Adapter Documentation/Adapter_Build_Instructions

Adapter Build Instructions

Adapter Build Instructions

This document covers the whole download/build/install process for the whole pEp software stack on platforms:

Debian Linux (10/stable)
MacOS (>10.14)

Adapters included in this build are:

pEpJNIAdapter
pEpPythonAdapter

The prerequisite for this manual is a machine running Debian Linux 10 with standard system utilities installed.

About this document

This is work in progress, if you have any problems please get in touch with me via:

IRC pEp Intern: heck
Mail: heck@pep.foundation

I depend on your feedback to improve this document and i will help you build your adapter. How to give feedback/suggestion:

Use the suggestions section in the appendix of this document
Change the document BUT mark your change, using “TODO:”
Ask me if you want to become a co-maintainer (YESSSS :)

I am the maintainer of this document, please do not change this document in any other way.
If you are not working at pEp, please contact irc://irc.freenode.net/#prettyeasyprivacy (please highlight sva)

Disclaimer

Currently, the instructions will only work using the following directory layout. These folder will be created while you cary out the instructions in this manual.

~/code        - source code main dir
~/code/common - shared source code, libs, etc...
~/include     - target install dir for header files
~/lib         - target install dir for libraries
~/bin         - target install dir for binaries
~/share       - target install dir for shared files

Installing System Dependencies

Debian Linux

As verified to work on Debian 10 (64bit) - minimal installation

Debian Packages

Prepare your linux system, by installing all these packages. Login as root, and execute the following line.

apt-get install sudo curl openssl libssl-dev pkg-config git mercurial capnproto clang sqlite3 libsqlite3-0 libsqlite3-dev python3 python3-lxml build-essential automake libtool autoconf make nettle-dev capnproto uuid-dev

Rust

Currently, in Debian10/stable the version of rust is too old. Please install rust Rust from www.rust-lang.org (1.46 or later)

Sudo

We need to configure sudo, so your normal user has sudo rights.
Login as root, and execute the following line, where has to be replaced with the username of your normal user.
Make sure to logout/login any session with the respective user, for the changes to become effective.

usermod -a -G sudo <USERNAME>

MacOS

As verified to work on MacOS 10.14

Disable SIP
Install xcode
Install xcode command line tools
Install Python from www.python.org (version 3.8.5 or later)
Install Rust from www.rust-lang.org (1.46 or later)
Install MacPorts from www.macports.org (latest version)

sudo port install gnupg2 mercurial capnproto nettle pkgconfig coreutils libtool autoconf automake

Building Dependencies

Sequoia

The pEp engine is based on Sequoia as encryption backend, written in Rust.
Login as your normal user and execute the following lines to build and install Sequoia.

please note: the build might be taking some time, depending on your system

mkdir -p ~/code/common/sequoia
cd ~/code/common/sequoia
git clone https://gitlab.com/sequoia-pgp/sequoia.git .
git checkout pep-engine
make build-release PYTHON=disable
make install PYTHON=disable PREFIX=$HOME

YML2

Build and install YML2 (more info: https://fdik.org/yml/index)

mkdir -p ~/code/common/yml2
cd ~/code/common/yml2
echo 'export PATH=$PATH:$HOME/code/common/yml2' >> ~/.bash_profile
source ~/.bash_profile
hg clone https://pep.foundation/dev/repos/yml2 .
make

libetpan

pEp Engine requires libetpan with a set of patches that have not been upstreamed yet.

mkdir -p ~/code/common/libetpan
cd ~/code/common/libetpan
git clone https://github.com/fdik/libetpan .
mkdir build
./autogen.sh --prefix=$HOME
make install

ASN1c

Build and install ASN1c interface description language.

mkdir -p ~/code/common/asn1c
cd ~/code/common/asn1c
git clone git://github.com/vlm/asn1c.git .
git checkout tags/v0.9.28 -b pep-engine
autoreconf -iv
./configure --prefix="$HOME"
make install

Building The pEpEngine

Download the engine source code.

mkdir -p ~/code/pEpEngine
cd ~/code/pEpEngine
hg clone https://pep.foundation/dev/repos/pEpEngine/ .

Create the build config file “local.conf” (paste the whole following code block into your shell)

echo '
PREFIX=$(HOME)
PER_MACHINE_DIRECTORY=$(PREFIX)/share/pEp

YML2_PATH=$(PREFIX)/code/common/yml2

ETPAN_LIB=-L$(PREFIX)/lib
ETPAN_INC=-I$(PREFIX)/include

ASN1C=$(PREFIX)/bin/asn1c
ASN1C_INC=-I$(PREFIX)/share/asn1c

OPENPGP=SEQUOIA
SEQUOIA_LIB=-L$(PREFIX)/lib
SEQUOIA_INC=-I$(PREFIX)/include

export PKG_CONFIG_PATH=$(PREFIX)/share/pkgconfig/
' > local.conf

Build the engine

make
make install
make db dbinstall

Test

Currently, we cant really “test” easily that the engine works, but lets check that the freshly built library is existing.

ls -l ~/lib/libpEpEngine*
-rwxr-xr-x 1 heck heck 1857744 Feb 24 23:59 /home/heck/lib/libpEpEngine.so (or .dylib on mac)

That looks good.

Building The Adapters

The build instructions for the various adapters follow here.
Login as normal user to execute those instructions.

libpEpAdapter

libpEpAdapter is a static library containing common functionality that can be shared across adapters. Most adapters require libpEpAdapter.

mkdir -p ~/code/common/libpEpAdapter/
cd ~/code/common/libpEpAdapter/
hg clone https://pep.foundation/dev/repos/libpEpAdapter/ .
make
make install PREFIX=$HOME

pEpPythonAdapter

This adapter requires libpEpAdapter, see build instructions above.

Dependencies Debian Linux

sudo apt-get install python3-setuptools libboost-python-dev libboost-locale1.67-dev

Dependencies MacOS

sudo port install boost

Build

mkdir -p ~/code/pEpPythonAdapter/
cd ~/code/pEpPythonAdapter/
hg clone https://pep.foundation/dev/repos/pEpPythonAdapter/ .
make

Test

make devenv

make envtest
*** init pEp 1.1.1 (null) (null)

That looks good

pEpJNIAdapter

This adapter requires libpEpAdapter, see build instructions above.

Dependencies Debian Linux

sudo apt-get install default-jdk

Dependencies MacOS

Install Java JDK from www.oracle.com

sudo port install gsed

Build

mkdir -p ~/code/pEpJNIAdapter/
cd ~/code/pEpJNIAdapter/
hg clone https://pep.foundation/dev/repos/pEpJNIAdapter/ .
make

Test

cd test/java/foundation/pEp/jniadapter/test/basic
make

.
.
.
main      : ======== TEST: 'startSync()' ================================ CTX: 'BasicTestContext' ========= [0.100 sec] === SUCCESS ======
main      : ======== TEST: 'Keygen2' ==================================== CTX: 'BasicTestContext' ========= [0.106 sec] === SUCCESS ======
Adapter.cc::shutdown - called
Adapter.cc::shutdown - sync_is_running - injecting null event

*** sync_protocol thread shutdown pEp sync protocol (null) (null)
Adapter.hxx::sync_thread - sync protocol loop ended
main      : ======== TEST: 'stopSync()' ================================= CTX: 'BasicTestContext' ========= [0.002 sec] === SUCCESS ======
main      : SUCCESS: 12
main      : FAILED : 0
main      : TOTAL  : 12

That looks good

Appendix

Suggestions

Please add your suggestions after this line. Thanks a lot for your contribution.