Signing requests for PSD2 APIs
To ensure that your request was not tampered with during transit, your application needs to sign it. Below we will explain the steps you need to take to correctly sign the request. You may also want to consult this reference: https://tools.ietf.org/html/draft-cavage-http-signatures-10
- The signing certificate
- Create the digest
- Create the signing string
- Sign with your private key
- Signature header
1. The signing certificate
Use your (PSD2) eIDAS QSEAL certificate issued by the Qualified Trust Service Provider of your choice. We recommend you to develop your application using the sandbox environment first, where you can use our example certificate if you don't have a real eIDAS certificate yet. In the examples below we have used the same example certificate so you can reproduce the resulting values.
2. Create the digest
The digest is a base64 encoded hash of the body:
- Take the body of your request or an empty string if there is no body.
- Pass the body through the SHA-512 hashing algorithm (SHA-256 is also allowed).
- Make sure the hashed output is binary. In other words; do not convert it to a string.
- Base64encode the output.
- Add the result to your digest header and make sure that you declare which hashing algorithm you have used.
An example of the digest header for an empty body using SHA-256 or SHA-512:
digest: sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= digest: sha-512=z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXcg/SpIdNs6c5H0NE8XYXysP+DGNKHfuwvY7kxvUdBeoGlODJ6+SfaPg==
3. Create the signing string
The signing string contains several headers depending on which API you are using, separated by line breaks. The order is not important as long as you define them in the same order in the signature header.
date: Tue, 18 Sep 2018 09:51:01 GMT digest: sha-512=z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXcg/SpIdNs6c5H0NE8XYXysP+DGNKHfuwvY7kxvUdBeoGlODJ6+SfaPg== x-request-id: 95126d8f-ae9d-4ac3-ac9e-c357dcd78811
Signing headers per API
Confirmation Availability of Funds:
psu-id(optional / if and only if included as a header of the HTTP request)
psu-corporate-id(optional / if and only if included as a header of the HTTP request)
tpp-redirect-uri(mandatory for ‘HTTP POST request)
tpp-nok-redirect-uri(optional / if and only if included as a header of the HTTP POST request)
4. Sign with your private key
The signature is the signing string signed with the private key:
- Create the signing string (see step 3).
- Sign it using RSA-SHA512 (RSA-SHA256 is also allowed) and the private key of the signing certificate.
- Base64 encode the output.
An example of the signature using the above information:
5. Signature header
The signature header consists of the following components:
|keyId||The serial number of the certificate as defined in 'TPP-Signing-Certificate' header, the format should be Integer not hex. You can use the openssl command line tool to find the serial number. For example:
|algorithm||Specify which algorithm was used when generating the signature:
The list of headers contained in the signature:
|signature||The result from step 4.|
The resulting signature header for our example:
signature: keyId="1523433508",algorithm="rsa-sha512",headers="date digest x-request-id",signature="y5o7gKxmfA6AT6IvZ5L89uWxhjcw0BPqDlfK6WX1pB5vKtOctzwustjHI6TjdgQMzQL9LAJX6izs5lVCB6Bjl/l3ntCt4rigJPzfTLbnSlxBhLcabru+KyC7pu00NasyMzl4kv/1jtxrBqzSsUvCz87IBSTLSeoPCJc4E5ME82Bdpss67RWcVe94UzLW8jsCqrncLxiMsD6d2ZQmnH/S7Gu9zk8g9eJovmLIaVLn4C5vW7khS63hSZf8qdTEDlMI/L+QgYVgZVIijKosYEnCB9tH5OYWS9cQ1g1NBrMHQASg/ZV8CxHkXizYg7gQoTGaKvSeD7QC172OqySblE1A9Q=="