136 lines
4.2 KiB
Markdown
136 lines
4.2 KiB
Markdown
# 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.
|
|
|