Security models and flows

All API communication in the context of PSD2 will be handled by using a combination of certificates. There are 2 distinct flows that 3rd party clients need to use in every transaction:

  1. Identification and Authentication
    1. This is achieved by establishing a mutual TLS connection, using a QTSP issued QWAC certificate
  2. Non-Repudiation and Message Integrity
    1. This is achieving by signing each request, according to the documentation, using a QTSP issued QSEAL certificate.

Note

  • wherever TLS is mentioned, we explicitly refer to TLS 1.2 or higher.

Also note that though we refer to BEC PSD2 APIs, BEC is a technical provider for our member banks, not an ASPSP. So rather than providing our own APIs, we provide PSD2 APIs on behalf of all of the Included ASPSPs. All examples are always implicitly in context of a specific bank from this list. Security model is implemented with strict separation between banks.

 

Getting Started

 

Certificates

To get started using the BEC PSD2 API's you need to have to the correct certificates. The certificates are issued by QTSP, and a list of them can be found here https://webgate.ec.europa.eu/tl-browser/#/. You need to obtain a QWAC and QSEAL certificate. In the context of the Development Sandbox you should use your production certificates also (or contact support for other options*).

 

The root certificate of the QTSP needs to be known by BEC. We monitor the above list on a regular basis, so as a rule of thumb we have installed root certificates for all QTSPs on this list. If your QTSP is not on this list - or if it has only been recently added - please get in touch with us to verify that we have QTSP's root certificate installed on our end.

 

Same certificates can be used to get access to all banks under BEC umbrella, but separate enrollment/onboarding is required for each bank and there is no implicit or explicit sharing of authorizations or access control between banks.

*) PSD2 support can help if you want to use certificates issued as test-certificates. Please include a reference to the CA and the specific certificate in your request.
OR if you have not yet received you certificates BEC can issue temporary test-certificates valid in the Sandbox only.

 

Enrollment

Before you can use the BEC API's you need to perform enrollment, this is described in detail more detail in the Onboarding section and in the documentation for the PSD2 TPP Enrollment API.

 

Request Flow

This section will describe a request flow, as seen from a TPP. There are several security features to be considered in order to achieve the highest level of Confidentiality, Integrity and Assurance.

 

Mutual TLS Authentication

The first step in the request flow is to authenticate by way of Mutal TLS Connection using a QTSP Issued QWAC Certificate. Please be aware that the Root Certificates of your QTSP must be known by BEC.

cURL example request should produce 403 but not 401
curl -E  --key  https://psd2api{bank_number}.prod.bec.dk/eidas/1.0/v1/test

 

Message Signing

 

Introduction

TPP's are required to sign request messages, this is in order to ensure the integrity of the message. The signature must be included in the HTTP header as defined in the following sections. The electronic signature of the TPP has to be based on a qualified certificate for electronic seals (QSEAL) issued by a QTSP as referred to earlier in this document. The certificate of the TPP has to indicate all roles the TPP is authorised to use. It should be noted that at the time of the request a TPP will only be granted use of the roles indicated in the specific certificate used at the time of the transaction, regardless of if that corresponds with the full set of roles the TPP as actually approved to use.

For further information and detailed examples please refer to the NextGenPSD2 XS2A Framework Implementation Guide, section 12, Page 216

 

Request Headers

 

Attribute

Type

Condition

Description

X-Request-IDUUIDMandatoryThe ID of the request, unique to the call as determined by the initiating party.
DigestStringMandatoryDigest of the request body created using either SHA-256 or SHA-512. Also for request with an empty/no body. In base64 encoding prefixed with the selected hash algorithm and a equals sign e.g. "SHA-256=xyz...."
SignatureStringMandatoryAs described below under Signature Header
TPP-Signature-CertificateStringMandatoryThe TPP certificate used for signing the request, in base64 encoding.
TPP-Redirect-URIStringConditionalURI of where the transaction flow shall be redirected to if required.
TPP-Nok-Redirect-URIStringConditionalURI of where the transaction flow shall be redirected to if an error is encountered if required.

 

Signature Header

For all requests, a "Signature" header must be present. The structure of a "Signature" header is defined in the following table which lists the requirements on the "Signature" header.

 

Element

Type

Condition

Requirement

keyIdStringMandatoryThe serial number and issuer-name of the Certificate included in the "TPP-Signature-Certificate" header. Formated as "SN=,CA="
algorithmStringMandatoryThe algorithm must identify the same algorithm for the signature as presented in the certificate of this Request. Currently "rsa-sha256" (SHA-256 with RSA) and "rsa-sha512" (SHA-512 with RSA) are supported.
headersStringMandatory

This is the list of headers that the signing string (see below) is based upon, this should include: Mandatory Attributes:

  • digest
  • x-request-id

Conditional Attributes:

  • tpp-redirect-uri (if and only if "tpp-redirect-uri" is included as a header of the HTTP-Request)

Please note that the headers must also actually be present in the request

signatureStringMandatory

The "signature" parameter is a base 64 encoded digital signature (using the QSeal privatekey), described as Base64(RSA-SHA256(signing string)) where the signing string is a newline (\n) separated list of key-values - constructed like this:

:

In the exact same order as described in the "headers" attribute.

Example (matching header attribute "digest x-request-id tpp-redirect-uri"). The SHA-256 with RSA signature of:

digest: SHA-256=ZuYiOtZkVxhjWmwTO5lOpsPevUNMezvk6dfb6fVhebM=
x-request-id: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721
tpp-redirect-uri: http%3A%2F%2Ftest%2Ftest

 

Example

Signature = 'keyId="SN=1213456789,CA=CN=PSD2 Test,OU=IT,O=BEC,C=DK",algorithm="rsa-sha256",headers="digest x-request-id tpp-redirect-uri",signature="38dlkjDLFJkdjf...."'
 

 

Signing example

Below request signs an empty body - hence the SHA 256 of the empty string - and the headers X-Request-ID "requestId" and TPP-Redirect-URI "http://test/test".

 

 

 
Then the signing string is
x-request-id: requestId
digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
tpp-redirect-uri: http%3A%2F%2Ftest%2Ftest
Using this example private key
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDE7cr3NcKowA9ta2s2A8PBP76onnPT9qcD02QdVybjtcNr3PLHbCPHwvO0LJ59uLW5MHmp17jH9drskrl115a5jWwLCeB0/040N5VygmuNLCHH0H3UQXWxP7exPXqcZQ5PIcpXhsLLAxNKpg9dG6AwGypWsYLjScFMXxaRHRFOBxIKPYqWSlSJJCCGoU/iBxY7HX2bEpZo1Kh87pxj44FagIT8htO91JC6fj7hV+iHW2vxikoh0y2jHj5akGraeKj5ORp763nRv/ONsxz8VyiHyNsVXitm5EQaj7v8sqOR+LmgcrfCLH+wkoPKNKUS449BnXcdZn+fvwcntOw5wRw1AgMBAAECggEAd4Ygd3TAxi1z76SP+MPGL2eiL7Okd5Uv/2lxTUGVUAYFK1V6YUGoYdlYkxW1yHawjUr3vPc6ptr42jefqv+D8vD8D6MaAcjnTVgjM9ImtxN/GUjY5lgot8EFm+TFo2DOk4bdycv4NMGUFu29S3S2ABys0NuCprMgSFs6Vi8/Tox5c6sPnwDxl0ETRdGKZXJg1G4Bi0RQlfGgPjyYQWDXlR7UZwbp2eu3El1SOyhd4uqLwLOlwgCeLAhyhlGB8gwkfYuU1UAREOmbJmQKV6luQlp5+g/7bEyNgtlfaZL77iJTpG1fKOQ/Vl/UaS6o5YIT0pnmjaAAKT54hSct+abgYQKBgQDkn8+iFJpoPHlXIHo/zYCKnn0b3qZflPXaZz8gHC1ZHoIWOQh9ZNxf0seVNINBOMtPrpvHhJ3Db6hhVvsIRuGUqiD3/UHvGNTIg8uF6QLpHuGXCR34BnW+oMXGQkKr4ttaAY1XBV4d43C94ptNWD/1q/CPG4F6NQq3LwdDpdEwTQKBgQDcgmZRhuCYAeqiOXnVUhe3vMmizQ90bHulbh2TEDU4k0ZOInjhZVKfI2xPyd2SyZhJPX9J74B4DaOhuMQnJN+GSlgZOMTuUvua3loRHVT4EcaxExryWmoRqNRaJcxU/0JUbIDDEdP14WW+aCRygfcBvrmpRF4EX2R2xPE3EcDPiQKBgFXfUPXoFzcfv9Ph9wkP/0AR15woPQWZxd6K+ULuUnou413FflLbF4tGeICqgMJ2uqbrRsfiH//QaMZnDVNGjGRyon+DOMi94u6N0lwx8U3us30vh3opswAvExosuS4mv41HF/efpIJFc4tfGkYq55s3Qdv+0Ns+IRA9MdVO6wvhAoGAbgHj97I5I7x5CLtxy3lr+a8GTODOX/+q48n+mRqR4oqenWZXNeMth9TNOTT1BEDsZ0V11jXUuo/bXVfnC7w6gy1drB+FJ3xgp09cUYN3m1aK8FYesF9o4Sx/3AVVXeYGekWzKx4ex2DOOGKOJE4wIz+6Mfa4jKfmX9Y6nIWP0jkCgYEA2IXyqYOCrScTjPNB9TygDSZe0/ZKjHNnkGJrmT5850bP+ADXY0JNVN6ROC0ROQ/ilkVjgZ6N8G/ojs+AK6RbkkLFAnV990frWA3CVMMTx0CIlwXckW/gzMMU6iNlSSblLE8uUTDG2oOd51isT12LVthfs84U4UR64G9En9Xnp6A=
-----END PRIVATE KEY-----
Using openssl produces below signature
> openssl dgst -sha256 -sign file_with_private.key file_with_signing_string.txt | base64
 
SS4Le+sNOhqeGN/pqgbPgF9DlzAA3rlz3Al71pZsEzjA71EDCTn/QPhSEYYDNN0X8/UuOpLsy2UE
KNx9HvIJRrd39QnXwUv4YBWUSfPbFR/65FXGjkcesRJGBW9HiGBeEDecw5ZGSmvXRF5h22SR+hT7
FrRLMp/Uuq8tNU8RQnbz6CtpZRZX+Ae9fWcgazNtNZEEivfKX/uBOfQJ+g5NQ1LBdvmgEHDy3Ogr
L+/wK4faFHIQI8tFo+7+RlQuXaFl10kz+9AE2H8twaEfCGhARxM8uTPSKwi94pwHGZwwtOSERBhw
BOi9wIM2dtfA6zp3Ykf93m9B5nM4RgyiwhMr4g==
Request (redacted)
X-Request-ID: requestId
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Signature: keyId="SN=5e20 ...,CA=...",algorithm="rsa-sha256",headers="x-request-id digest tpp-redirect-uri",signature="SS4Le+sNOhqeGN/pqgbPgF9DlzAA3rlz3Al71pZsEzjA71EDCTn/QPhSEYYDNN0X8/UuOpLsy2UEKNx9HvIJRrd39QnXwUv4YBWUSfPbFR/65FXGjkcesRJGBW9HiGBeEDecw5ZGSmvXRF5h22SR+hT7FrRLMp/Uuq8tNU8RQnbz6CtpZRZX+Ae9fWcgazNtNZEEivfKX/uBOfQJ+g5NQ1LBdvmgEHDy3OgrL+/wK4faFHIQI8tFo+7+RlQuXaFl10kz+9AE2H8twaEfCGhARxM8uTPSKwi94pwHGZwwtOSERBhwBOi9wIM2dtfA6zp3Ykf93m9B5nM4RgyiwhMr4g=="
TPP-Signature-Certificate: MIIEzTCCA7WgAwIBAgIUXiB4 ... DRjdbTI5YebVRci1/mFjbtmHl+SpV8gr91X9un
TPP-Redirect-URI: http%3A%2F%2Ftest%2Ftest