MirageOS Taler Exchange

OCaml-based unikernel implementation of a GNU Taler exchange.

Implementation status

MTE is still experimental and under development.

Currently supported Exchange API endpoint (protocol version v31):

• /terms
• /privacy
• /seed
• /config
• /management/*
• /keys

Developement setup

Because MTE compile to an unikernel, it requires to be given a TAP interface for network connectivity, and a file (formated to FAT) to use for cryptographic keys storage. It also require a connection to a PostgreSQL database.

Network

We need to make a bridge device and asign it the 10.0.0.1 address, then attach a TAP device to it. To create the appropriate virtual network run network.sh.

Be sure that your firewall (e.g. iptables) allows to reach the server and for the server and database to comunicate.

Database

To setup PostgreSQL, first you will need to initialize a database cluster, create a user and a database. For that we recommand to follow the archlinuxwiki documentation https://wiki.archlinux.org/title/PostgreSQL . It is important to set the database username to 'mte' and the database name to 'taler-exchange', as those value are hardcoded in setup scripts/config.

PostgreSQL need to be configured to listen and accept connection at address 10.0.0.1 on port 5432 (same address as our virtual network bridge, this is for simplicity, as network configuration can be quite cubersome). Edit PostgreSQL's configuration file to allow that (PostgreSQL's configuration file location may vary depending on your system).

/var/lib/postgres/data/postgresql.conf

listen_addresses = '10.0.0.1'

/var/lib/postgres/data/pg_hba.conf

# TYPE  DATABASE        USER            ADDRESS                 METHOD
# IPv4 local connections:
host    all             all             10.0.0.1/24           trust

You may need to restart PostgreSQL after configuration change, or if the bridge at 10.0.0.1 was not yet UP.

Futhermore the database must be initialized (with sql tables, etc) before starting the server. We aim for database compatibility with GNU Taler exchange. To initialize the database use the tools/dbinit.sh script, it aggregates together the GNU Taler exchange's SQL files required to initialize the database and send commands to the PostgreSQL server with psql. (Or directly use a compatible version of GNU Taler Exchange's taler-exchange-dbinit tool)

Prepare SQL queries and create the various elements (e.g. sql tables) required to be in the database.

./tools/dbinit fetch
./tools/dbinit build
./tools/dbinit init

Dependencies

MTE use the opam package manager and the dune build system.

Create a dedicated opam switch, pin libraries to the required version and install them.

make setup-switch

For compilation to a solo5 unikernel, we also need to "vendor" some libraries.

make vendors

Assets, configuration file and keys

Create a keys/ folder, generate a fresh master key for the server (and also a file with the required postgres_password to connect to the database).

make keys

Create keys/secmod.fat file that will be the FAT block storage given to MTE. MTE will use it to store it's signatures and denominations keys.

make secmod.fat

Create a assets/ folder containing default terms of use files and a default configuration file.

make assets

Complete the configuration file by writing master public key of the server we previously generated into it.

make config

Build and run

Now everything should be in place to build and run MTE:

make build
make run

Access the server on http://10.0.0.2:3434/

Tests

Run tests with

dune runtest

This will run tests for various utility functions, binary formats and cryptographic functions. It also test that MTE's binary formats and cryptographic signature on the various fields of /keys API are consistent with the reference implementation.

It is also possible to run a test scenario of the /management API with the /test/management.sh script. It uses mte-offline-tool executable to produce various keys, signatures and JSON objects used in the /management API. Note that this script assumes a server is already running at http://10.0.0.2:3434, and that it will write changes to the database.