README.md 7 KB
Newer Older
Sietse Ringers's avatar
Sietse Ringers committed
1
# irmago   [![GoDoc](https://godoc.org/github.com/privacybydesign/irmago?status.svg)](https://godoc.org/github.com/privacybydesign/irmago) [![Go Report Card](https://goreportcard.com/badge/github.com/privacybydesign/irmago)](https://goreportcard.com/report/github.com/privacybydesign/irmago)
2

Sietse Ringers's avatar
Sietse Ringers committed
3
`irmago` is an IRMA implementation in Go. It contains multiple libraries and applications:
Sietse Ringers's avatar
Sietse Ringers committed
4

5
6
7
8
9
10
11
12
13
* The commandline tool [`irma`](https://irma.app/docs/irma-cli/), which contains an [IRMA server](https://irma.app/docs/irma-server/); subcommands for manipulating [IRMA schemes](https://irma.app/docs/schemes/), generating IRMA issuer public/private keypairs, performing test IRMA sessions on the command line; and more.
* The Go library [`irmaserver`](https://irma.app/docs/irma-server-lib/) providing a HTTP server that handles IRMA session with the [IRMA mobile app](https://github.com/privacybydesign/irma_mobile), and functions for starting and managing IRMA sessions.
* The root package `irma` contains generic IRMA functionality used by all other components below, such as parsing [IRMA schemes](https://irma.app/docs/schemes/), parsing [IRMA metadata attributes](https://irma.app/docs/overview#the-metadata-attribute), and structs representing messages of the IRMA protocol.
* The Go package `irmaclient` is a library that serves as the client in the IRMA protocol; it can receive and disclose IRMA attributes and store and read them from storage. It also implements the [keyshare protocol](https://github.com/privacybydesign/irma_keyshare_server) and handles registering to keyshare servers. The [IRMA mobile app](https://github.com/privacybydesign/irma_mobile) uses `irmaclient`.

## Documentation

Technical documentation of all components of `irmago` and more can be found at https://irma.app/docs.

14
15
16
17
18
19
## Running

The easiest way to run the `irma` command line tool is using Docker.

    docker-compose run irma

20
21
22
23
24
For example, to start a simple IRMA session:

    IP=192.168.1.2 # Replace with your local IP address.
    docker-compose run -p 48680:48680 irma session --disclose pbdf.sidn-pbdf.email.email --url "http://$IP:48680"

25
You can run the `irma keyshare` services locally using the test configuration in `testdata/configurations`.
26

27
    # To run the IRMA keyshare server
28
    docker-compose run -p 8080:8080 irma keyshare server -c ./testdata/configurations/keyshareserver.yml
29
30
    # To run the MyIRMA backend server
    docker-compose run -p 8081:8081 irma keyshare myirmaserver -c ./testdata/configurations/myirmaserver.yml
31

32
33
## Installing

Sietse Ringers's avatar
Sietse Ringers committed
34
    git clone https://github.com/privacybydesign/irmago
35

Sietse Ringers's avatar
Sietse Ringers committed
36
`irmago` and its subpackages use Go modules for their dependencies. The `go` command will automatically download dependencies when needed.
37

Sietse Ringers's avatar
Sietse Ringers committed
38
To install the `irma` command line tool:
39
40
41

    go install ./irma

42
You can also include the `irma` command line tool in a Docker image, using a base image of your choice. The default base image is Debian's `stable-slim`.
43

44
    docker build --build-arg BASE_IMAGE=alpine -t privacybydesign/irma:edge .
45

46
When you build for production, we recommend you to build the [latest release](https://github.com/privacybydesign/irmago/releases/latest). You should replace `v0.0.0` with the latest version number.
47

48
    docker build -t privacybydesign/irma https://github.com/privacybydesign/irmago.git#v0.0.0
49
50
51
52
53
54
55

In case you want to build `v0.8.0` or lower, then you should do some extra steps. The `Dockerfile` was not part of the repository at that time.

    VERSION=v0.8.0
    git checkout $VERSION
    git checkout master -- Dockerfile
    docker build -t privacybydesign/irma:$VERSION .
56

57
58
## Running the unit tests

59
Some of the unit tests connect to locally running external services, namely PostgreSQL and an SMTP server running at port 1025. These need to be up and running before these tests can be executed. This can either be done using `docker-compose` or by following the instructions below to install the services manually.
60

Sietse Ringers's avatar
Sietse Ringers committed
61
#### PostgreSQL
62

Sietse Ringers's avatar
Sietse Ringers committed
63
64
65
66
67
68
69
70
71
72
73
74
75
 * Install using e.g. `brew install postgresql`, or `apt-get install postgresql`, or via another package manager of your OS.
 * Prepare the database and user:

       create database test;
       create user testuser with encrypted password 'testpassword';
       grant all privileges on database test to testuser;

   This only needs to be done once. No table or rows need to be created; the unit tests do this themselves.

#### SMTP server
For the SMTP server you can use [MailHog](https://github.com/mailhog/MailHog) (see also their [installation instructions](https://github.com/mailhog/MailHog#installation)):
 * Install using `brew install mailhog` or `go get github.com/mailhog/MailHog`.
 * Run using `MailHog`, or `~/go/bin/MailHog`, depending on your setup.
76

Sietse Ringers's avatar
Sietse Ringers committed
77
For the unit tests it only matters that the SMTP server itself is running and accepts emails, but MailHog additionally comes with a webinterface showing incoming emails. By default this runs at <http://localhost:8025>.
78

Sietse Ringers's avatar
Sietse Ringers committed
79
### Running the tests
80

81
82
83
84
85
In case you chose to start PostgreSQL and MailHog using `docker-compose`, you first need to start these services:

    docker-compose up

When PostgreSQL and MailHog are running, the tests can be run using:
Sietse Ringers's avatar
Sietse Ringers committed
86
87
88
89
90

    go test -p 1 ./...

* The option `./...` makes sure all tests are run. You can also limit the number of tests by only running the tests from a single directory or even from a single file, for example only running all tests in the directory `./internal/sessiontest`. When you only want to execute one single test, for example the `TestDisclosureSession` test, you can do this by adding the option `-run TestDisclosureSession`.
* The option `-p 1` is necessary to prevent parallel execution of tests. Most tests use file manipulation and therefore tests can interfere.
91

92
### Running without PostgreSQL, MailHog or Docker
93

94
If installing PostgreSQL, MailHog or Docker is not an option for you, then you can exclude all tests that use those by additionally passing `--tags=local_tests`:
95

Sietse Ringers's avatar
Sietse Ringers committed
96
    go test -p 1 --tags=local_tests ./...
97

98
99
100
101
102
103
104
105
106
107
108
109
### Running without Go

You can also run the tests fully in Docker using the command below. This is useful when you don't want to install the Go compiler locally. By default, all tests are run one-by-one without parallel execution.

    docker-compose run test

You can override the default command by specifying command line options for `go test` manually, for example:

    docker-compose run test ./internal/sessiontest -run TestDisclosureSession

We always enforce the `-p 1` option to be used (as explained [above](#running-the-tests)).

110
## Using a local Redis datastore
111
`irmago` can either store session states in memory (default) or in a Redis datastore. For local testing purposes you can use the standard [Redis docker container](https://hub.docker.com/_/redis):
112
113
114
115
116
117

```
docker pull redis
docker run --name redis-test-instance -p 6379:6379 -d redis
```

118
You can then start `irma` with the store-type flag set to Redis and the [default configuration file](testdata/configurations/redis.yml).
119
120

```
121
irma server -vv --store-type redis --redis-addr "localhost:6379" --redis-allow-empty-password --redis-no-tls
122
123
124
```

<!-- vim: set ts=4 sw=4: -->