Adapter/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.10)

Adapters included in this build are:

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 contribute:

  • 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

As 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)

Limitations

Component Versions

Currently, if you follow these instructions, what will be built is just the very latest commit from each software repository. Please note that we use a repo “master/HEAD” is unstable policy. That means if you like to build a stable version of an adapter and its dependencies, you would need to build a released version of the adapter and its dependencies. But as of now, these instructions dont describe how to build specific versions of adapters/engine/etc.

Dir Layout

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.

~/src               - source src main dir
~/local/include     - target install dir for header files
~/local/lib         - target install dir for libraries
~/local/bin         - target install dir for binaries
~/loca/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.

This will install all the dependencies listed below.

Toolchain

system: sudo curl
build: git build-essential python3 clang pkg-config

Component Dependencies

sequoia: nettle-dev capnproto libssl-dev
yml2: python3-pip python3-lxml
libetpan: libtool autoconf
pEpEngine: uuid-dev sqlite3 libsqlite3-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) After the rust installation has finished, logout and back in to refresh your shell environment.

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.

MacOS

As verified to work on MacOS 10.14

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: this build might take some time, 1, 2, or 3 coffees, depending on your system

YML2

Install YML2 (more info: https://fdik.org/yml/index)

libetpan

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

ASN1c

Build and install ASN1c interface description language.

Building The pEpEngine

Versions

The pEpEngine releases are tagged and have major, minor and patch numbers. The format of the release tags is: Release_<major>.<minor>.<patch>. Use git tag after the the git clone command to get a list of all tags/releases. Of any given minor release, please always use the latest patch release, that is, where <patch> component has the highest number.

e.g. git checkout Release_2.1.33

Build

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

Build the engine

Test

Currently, we can’t really “test” easily enough that the engine works, without installing external dependencies to run the test suite. But lets check that the freshly built library is existing.

That looks good.

Building The Adapters

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

Versions

Adapter releases are tagged and have major, minor and patch numbers. The format of the release tags is: Release_<major>.<minor>.<patch>. Use git tag after the the git clone command to get a list of all tags/releases. Of any given minor release, please always use the latest patch release, that is, where <patch> component has the highest number.

e.g. git checkout Release_2.1.33

libpEpAdapter

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

pEpPythonAdapter

This adapter requires libpEpAdapter, please see build instructions above.

Dependencies Debian Linux

Dependencies MacOS

Build

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

Build the adapter

Test

That looks good

pEpJNIAdapter

This adapter requires libpEpAdapter, please see build instructions above.

Dependencies Debian Linux

Dependencies MacOS

Build

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

Build the adapter

make

Test

That looks good.

pEpJSONServerAdapter

The p≡p JSON Server Adapter (or short: JSON Adapter) also needs the libpEpAdapter; see above.

Because documentation shall be as near as the code it belongs to the most accurate (and least outdated) documentation is in the README.md in the root of JSON Adapter’s source repo. If that README.md contains errors, is outdated or omitting important informations, please file a bug in the “JSON” project of Jira.

Requirements / Dependencies

  • C++ compiler: tested with g++ 4.8, 4.9, 8.3 and clang++ 2.8. Newer versions should work, too. If not -> File a bug!
  • GNU make
  • libboost-thread-dev (tested with 1.58, 1.62, 1.67, 1.70 and 1.74)
  • libboost-program-options-dev
  • libboost-filesystem-dev
  • p≡p Engine (which needs sequoia, a patched libetpan, libboost-system-dev)
  • libpEpAdapter
  • webserver
  • OSSP libuuid

The directory structure of the JSON Adapter does not – yet – fulfill the requirements described above; that is fixed soon.

For the time being, just go into the server subdirectory and type make.

Running the JSON Adapter

The stand-alone JSON Adapter (a.k.a. pEp-mini-json-adapter) can be started directly on command line, e.g. like this:

If it starts up without errors you should got a file ~/.pEp/json-token which contains the address and port the JSON Adapter is listening on, and a “security-token” which mus be given in every function call to the JSON Adapter to prevent other users on the same machine from using your JSON Adapter.

You can now open http://127.0.0.1:4223/ (it is the default port, if available. Consult the json-token file for the actually used port) in your webbrowser and see a demo page where you can emit function calls via the JSON Adapter to the pEpEngine.

Appendix

Suggestions

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