CAUTION: This project may not suite production use and is mainly intended for testing!

Open Banking eIDAS broker

The broker service provides possibility to use eIDAS certificates (in practice any X.509 certificates) for generating signatures and sending HTTP requests over mTLS connections without need to expose private keys of the certificates with the service client.

The web API of the broker service consists of 2 endpoints:

/sign -- for signing received data with a QSeal certificate and returning this signature back;
/make-request -- for making HTTP request over mutual TLS connection established with a QWAC certificate and returning response back.

Access to the broker service APIs is provided over mTLS and authentication of the client is done based on the client certificate. The client certificate and the broker server certificate shall be signed using the same CA certificate.

The broker service is primarily designed to be called from enable:Banking aggregation SDK, which provides special BrokerPlatform class offloading signing and mTLS funtionality to the broker.

Accessing ASPSP APIs through eIDAS broker

The flow of the calls between client, broker service and ASPSP looks like this:

   [Client premises]            --   [Broker service holding eIDAS keys]   --   [Open banking API (ASPSP)]

1. OB API request to be signed  ->   Signing the data using a QSeal
                                     certificate named by the client
   Request signature            <-   and returning the signature

                                     Forwarding the request to an ASPSP 
2. OB API request to be sent    ->   over mTLS established with a QWAC     ->   ASPSP gets complete API
                                     certificate named by the client            request, verifies the
                                                                                signature, and responses
   Response from the ASPSP      <-   Returning the response back to the    <-   to the broker service
                                     initiating party

The client may request to use different certificates (identified by URI) and to forward arbitrary requests (to different ASPSPs).

Generation of certificates for client - broker interaction

As mentioned earlier mTLS connector is used for securing interactions between the client (aggregation SDK using BrokerPlatform) and the broker service. This provides adequate level of security even when the client and the broker use are connected through Internet (the same mechanism is used for securing open banking APIs).

The most important thing in ensuring security of the interaction is keeping private keys securely stored and not transferring them over insecure channels. Thus CA and server private keys shall be generated at the broker site (assuming that client and broker are located in different networks and secure communication between them can not be guaranteed), while client private key is generated at the client site. The client certificate is signed with CA key at the broker site; for this certificate signing request (CSR) is transferred from the client site to the broker, which can be done over insecure channels.

CA

First of all CA private key shall be generated (this is done at the broker site); in the examples below we are using OpenSSL command line utility.

openssl genrsa -out ca.key 4096

And CA certificate shall be generated (if necessary, replace values under -subj parameter with your values).

openssl req -new -x509 -days 365 -key ca.key -out ca.crt \
    -subj "/C=FI/ST=Uusima/L=Helsinki/O=ExampleOrganisation/CN=www.bigorg.com"

Server

Then server (broker) private key can be generated (again at the broker site).

openssl genrsa -out server.key 4096

And server CSR is to be generated. Make sure the CN value in the subj parameter matches the host name, which will be used by the broker (in the example below localhost is used for the case when we are testing broker service locally, i.e. running on the same machine, which is used for accessing it).

openssl req -new -key server.key -out server.csr \
    -subj "/C=FI/ST=Uusima/L=Helsinki/O=ExampleServerOrganisation/CN=localhost"

The server certificate is to be signed with ca.key. To ensure security DO NOT use md5 message digest. In the examples below we use sha256.

openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt -sha256

Client

Finally a private key for the client certificate can be generated (this is done at the client site).

openssl genrsa -out client.key 4096

And client CSR is generated the same way how it's done for the server.

openssl req -new -key client.key -out client.csr \
    -subj "/C=FI/ST=Uusima/L=Helsinki/O=ExampleClientOrganisation/CN=www.localorg.com"

Finally client.csr can be transferred to the site where ca.key is available and signing of the client certificate with ca.key can be done.

openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 02 -out client.crt -sha256

The generated client certificate (client.crt) can be shared back with the client.

Verification of the certificates (optional)

You can verify server and client certifiactes against CA certificate using the following commands.

openssl verify -purpose sslserver -CAfile ca.crt server.crt

openssl verify -purpose sslclient -CAfile ca.crt client.crt

Building an image and starting a container

In order to build an image you need to:

Have docker installed
Put you QWAC (mTLS) and QSeal (signature) certificates (if your API requires those) into open_banking_certs/ directory.
You can put certificates in an arbitrary order/names. Later you will have to provide paths to those certificates.
It is proposed to put certificates in the following order:

Bank1
- server.key
- server.crt
- signature.key
- ca_cert.crt (optional)
Bank2
- server.key
- server.crt
- signature.key

Put broker certificates into broker_tls/ directory under following names:
- server.key # private server (broker) certificate
- server.crt # public server (broker) key
- ca.crt # public certificate authority certificate If you want to generate self-signed certificates, see instructions below
Go to the directory with Dockerfile
Run docker build -t <image_name> . (probably you need to prepend this command with sudo)
Start built image:

docker run -d \
    --name <container_name> \
    -p 443:80 \
    --mount type=bind,source="$(pwd)"/open_banking_certs/,target=/app/open_banking_certs/ \
    <image_name>

You can also specify verify_cert environment variable using -e flag if you want you requests to banks to be verified against QWAC certificate chain (if it is provided).

Go to http(s)://localhost:<host_port> to verify that everything works (you will need to provide broker certificates with you requirest in order to see the page)

Check available endpoints

Container endpoints documentation is available at /docs or /redoc:
http(s)://localhost:<host_port>/docs
http(s)://localhost:<host_port>/redoc

igarciar / open_banking_eidas_broker Goto Github PK