This is a server that sits between IRMA tokens such as the IRMA app on the one hand, and authorized service or identity providers on the other hand. It handles all IRMA-specific cryptographic details of issuing credentials and verifying disclosure proofs on behalf of the service or identity provider. It exposes a RESTful JSON API driven by JWTs for authentication.

The API that this server offers is described here. We offer a client of the API exponsed by this server in the form of a javascript library, irma_js, that you can use in your webpages to easily issue and verify credentials. The flow of the various interactions of these components in a typical IRMA session is shown here.

See below to run or build the server yourself. Alternatively, you can use our demo API server, which is setup to be very permissive (but only in the demo domain). It is hosted at https://demo.irmacard.org/tomcat/irma_api_server/, you can find its signing key here.

Currently, the server expects all configuration files in a single directory. The location of this server can be configured by setting a environment variable called IRMA_API_CONF, for example,

IRMA_API_CONF=/etc/irma_api_server gradle appRun

or

IRMA_API_CONF=/etc/irma_api_server ./start.sh

depending if you are running a build or not. If this variable is left empty, then the server will try the following locations:

1. src/main/resources
2. /etc/irma_api_server
3. C:\irma_api_server
4. ~/irma_api_server

The main configuration file is a json file called config.json. In src/main/resources a sample configuration file called config.SAMPLE.json is included, showing all options, their defaults, and what they mean.

All credential descriptions, issuer public keys and possibly private keys - that is, the scheme manager information - are expected in a subdirectory called irma_configuration within the configuration directory. There are several options:

• You can use our irma-demo scheme manager (which includes issuer private keys) for experimenting,
• You can use our pbdf if you want to verify attributes issued by the Privacy by Design Foundation,
• you can create your own scheme manager containing your own issuers and credential types.

For example, in the first case, you would cd to your configuration directory, and do

mkdir irma_configuration 2>/dev/null
cd irma_configuration
git clone https://github.com/privacybydesign/irma-demo-schememanager irma-demo

For more information, see the README.md of the irma-demo scheme manager.

You can change the ports on which a build of the server listens as follows:

./start.sh --runnerArg="httpPort=8080" --runnerArg="httpsPort=8443"

If you want to change the ports when using gradle appRun to start the server, you'll have to modify build.gradle.

The server uses JSON web tokens (JWT's) for verifying the authenticity of incoming requests and for signing its output, in the case of verification. Before you can use the server, you need to set up some of the public and private keys for this. For this we have included a bash script keygen.sh, that uses the openssl command line tool. All keys must be in the DER format. In more detail:

• sk.der in the configuration path is used to sign the final message to the service provider in a verification session. This can easily be generated by executing utils/keygen.sh (This will also generate the corresponding public key pk.der, which is not needed by the server, except when running unit tests.)
• Identity and service providers must send their requests to the server in the form of JSON web tokens. Thus the server needs to know the public keys of all authorized service and/or identity providers. These are also stored in issuers/ and verifiers/ in the configuration path; see the configuration file for details.

Neither utils/keygen.sh nor utils/preparetest.sh will overwrite existing files.

All config entries in config.json, as well as all the jwt keys (i.e. sk/pk.der) can also be defined as environment variables. In this way, irma_configuration is the only extra directory/set of files that is needed to run the server. All entries in config.json can be 'converted' to an environment variable by converting the entry to upper case and prepending it with IRMA_API_CONF_. For instance the config entry "enable_verification": true,, would be set with an environment variable as follows:

export IRMA_API_CONF_ENABLE_VERIFICATION="true"

Config entries that are set via an environment variable always take priority over entries in the config file. For the config entries that require a json list (i.e. the entry authorized_idps), you can use raw json as a value for the environment variable.

JWT keys can also be set via environment variables, but since these key files are binary, they first must be converted to base64 in order to be stored in an environment variable. To store the irma_api_server jwt private key in an environment variable, you should use the following set of commands:

cat sk.der | base64 -w0
export IRMA_API_CONF_BASE64_JWT_PRIVATEKEY="<OUTPUT OF COMMAND ABOVE>"

Public keys for issuers/verifiers can also be set via environment variables. If you want for instance to set the key for the issuer 'MijnOverheid' (file: issuers/MijnOverheid.der), you can use the following environment variable/set of commands:

cat issuers/MijnOverheid.der | base64 -w0
export IRMA_API_CONF_BASE64_JWT_ISSUERS_MIJNOVERHEID="<OUTPUT OF COMMAND ABOVE>"

Like with the config entries, keys that are set via environment variables are prioritized over keys that are located in files.

The gradle build file should take care the dependencies. To run the server in development mode simply call:

gradle appRun

You can produce a .war file suitable for Tomcat 7 by running

gradle war

Alternatively, you can build the server, resulting in a standalone package that depends only on Java, as follows:

gradle buildProduct

The resulting package will then be stored in build/output/irma_api_server and can be started with start.sh. NOTE: before runnung gradle war or buildProduct, be sure to run git submodule update --init first! This fetches the IRMA configuration and keys that are used for the unit tests, which are automatically performed by these two gradle commands.

You can run the included unit tests by running gradle test; in this case src/test/resources will always be used as the configuration directory (which comes with its own configuration files for this purpose, as well as irma_configuration as a git submodule. Be sure to run git submodule update --init!).

A test service provider and identity provider, written in node.js, is included; see utils/testsp.js and utils/testip.js respectively. If you haven't done so already, you should install the dependencies (assuming you already have node.js installed):

npm install qrcode-terminal request jsonwebtoken fs

Furthermore, you should run the utils/preparetestjs.sh script to prepare testing keys (which will be placed in src/main/resources), and make sure that you enable these test keys in your config.json in src/main/resources, for example. Using config.sample-demo.json as the configuration file should do the trick.

After this you can run it using:

node utils/testsp.js http://<SERVER>:8081 [configuration_dir]

where <SERVER> refers to the IP address or hostname of your running irma_api_server, and where the optional second argument specifies the configuration directory in which the script is to find the JWT keys (if absent, src/main/resources is assumed). Make sure you use an address that the IRMA app can also reach (we usually use a local ip address for testing).

For more sophisticated examples, see irma_js.