eIDAS Certificate Handling

The purpose of this section is to describe how Klarna protects the eIDAS (electronic IDentification, Authentication and trust Services) certificates of their customers

The eIDAS certificate is used for the following purposes:

  • Identification and authentication of the customer towards the ASPSP (QWAC [Qualified Website Authentication Certificate], transport layer).
  • Encryption of the traffic between Klarna and ASPSP (QWAC, transport layer).
  • Generating a digital signature of the payload to ensure the integrity and as an additional method for identification/authentication (QSealC, [Qualified Electronic Seal Certificate], application layer).

Security Measures

As the eIDAS certificate offers the ability to prove the identity of the customer, the certificate is considered as sensitive and highly confidential data and must be protected and secured.

Non-technical Security Measures

  • In the contract between the customer and Klarna it is clearly stated that it is an obligation of Klarna to only use the eIDAS certificates in the scope of the defined services of the agreement.
  • The lifecycle of the certificates fully remains in the responsibility of the customer. The certificates used for the Open Banking by Klarna. integration can be revoked by the customer at any time.
  • The customer can (and should) use a separate set of eIDAS certificates only for the Open Banking by Klarna. integration. This makes the certificate lifecycle independent and ensures business continuity of the other operational business of the customer in case of a revocation and creates a direct mapping from the specific eIDAS certificates to the Open Banking use-case. The EBA describes/recommends the same in one of their published letters:

However, in the specific cases where PSPs provide services through agents or EEA branches, or where they have outsourced to technical service providers some of the activities related to access to the online accounts held within an ASPSP, the EBA hereby clarifies that CAs should encourage these PSPs to consider using multiple certificates simultaneously: one per agent, EEA branch or technical service provider. This should ensure business continuity and better risk management of these PSPs because the legitimacy of one certificate would not be affected by the revocation of any other. PSPs remain fully responsible and liable for the acts of their agents and outsource providers as well as for the revocation and updating of the eIDAS certificates used by them.

Technical Security Measures

To offer the best security and protection of the eIDAS certificates and private keys, the customer can choose between two approaches:

  • Klarna HSM: To allow Klarna to fully manage the process, the customer can share the certificates with Open Banking. The certificates will be uploaded to an HSM (hardware security module), which is a proven and certified security platform for managing and storing private keys in a highly protected, architecturally secure system. No one has access to the keys and only the system itself can generate signatures with the HSM based on the customer's eIDAS certificates.
  • Customer operated HSM Reverse API: If the customer wants to be in full control of their eIDAS private keys and does not want to share their certificates with Klarna, Open Banking offers the possibility to integrate a HSM Reverse API. All signing requests will be sent to the customer and it is their responsibility to generate the corresponding signatures within their own environment.

Using the Klarna HSM

There are three procedures for adding the customer's eIDAS certificate to Klarna's HSM.

  • Send Klarna the private key, public key and the cert-file of the eIDAS certificates attached to an encrypted email, preferable via KeePass or GnuPG with symmetric passphrase (gpg -c FILE). Please do not include the password in this email, use a separate communication channel for it.
  • Klarna can generate the private key directly in the HSM. This will ensure that nobody will ever see the private key, but there is no way to share it with the customer later since it is protected by the HSM.
  • Visit one of the Klarna offices and upload the private key to the HSM yourself.

Using a Customer owned/operated HSM Reverse API

Klarna supports HSMs that are owned/operated by the customer. This enables the customer to fully control the eIDAS certificate private keys in their own HSM.

Requirements

  • A secure connection from Klarna to the customer’s HSM Reverse API service.
  • Implementation of Klarna’s “HSM Reverse API” (see below).
  • The HSM Reverse API must support signing of payloads with different algorithms that are typically used for the QWAC and QSealC certificates.

Implementation of the HSM Reverse API

The HSM reverse API standardizes the complex HSM API. It helps to secure the connection between Klarna and the customer's HSM because Klarna does not need direct access to the HSM itself.

The following is the definition of the reverse API the customer has to provide and operate. Thus the base URL has to be communicated to Klarna by the customer.

HSM Reverse API Definition

For each call authentication and encryption is done through JSON Web Encryption (JWE) as explained on the page Secure Communication. However, please note that in this scenario the HSM Reverse API service is the server and Klarna is the client and separate key pairs are needed.

Request

POST /sign HTTP/1.1

<payload>
curl -X "POST" "/sign" \
         -d $'<payload>'

The payload should be structured as follows:

{
    "session_id": String,

    "alias": String,
    "algorithm": String,
    "payload": String,
    "tls_client_auth": Boolean,

    "digest_hash": ?String,
    "digest_hash_algorithm": ?String,
    "digest_payload": ?String
}

session_id String, required

The XS2A API session_id is used to correlate this request to an existing XS2A session.

alias String, required

Identifier for the certificate which must be used to sign the payload.

Examples: klarna-qwac-2020-05-01, klarna-qseal-2020-05-01

algorithm String, required

Algorithm to use for signing.

Currently the following values are supported, the most important ones first:

  • SHA256_RSA
  • SHA512_RSA
  • SHA256_RSAPSS
  • SHA384_RSA
  • SHA224_RSA
  • SHA1_RSA

Please note that the importance can change at any time and that banks could require additional algorithms in the future.

payload String, required

Base64 encoded payload that must be signed after decoding it.

tls_client_auth Boolean, required

The tls_client_auth property indicates whether or not the signature is part of the TLS client authentication for an HTTPS mTLS handshake.

Some banks generate the signature based on a previously calculated hash of the payload and not based on the payload itself. In this case Klarna provides the payload, the hash and the used hash algorithm as digest_payload, digest_hash and digest_hash_algorithm, respectively. This allows the customer to see the actual payload and verify the hash that will be signed.

digest_hash String, optional

Hash of the digest_payload property generated with the digest_hash_algorithm.

digest_hash_algorithm String, optional

The hash algorithm used to generate the digest_hash from the digest_payload.

Currently only one value is supported: SHA256

Please note that banks could require additional algorithms in the future.

digest_payload String, optional

Base64 encoded input for the digest_hash.

Response

{
    "signature": String
}

signature String, always present

Signature generated by the HSM, encoded as Base64.

Request

{
    "session_id" : "175cnd9qoj7i9sh4ihf8ch8jrnc6th7t",

    "alias" : "klarna-qseal-2019-07-01",
    "algorithm" : "SHA256_RSA",
    "payload" : "KHJlcXVlc3QtdGFyZ2V0KTogcG9zdCAvb2F1dGgyL3Rva2VuCmRhdGU6IFdlZCwgMzEgSnVsIDIwMTkgMTU6MTI6MjYgR01UCmRpZ2VzdDogU0hBLTI1Nj13MG15bXVMOGFDcmJKbW1hYnMxcHl0WmhvbjhsUXVjVHVKTVV0dUtyK3V3PQp4LWluZy1yZXFpZDogNjYwOTBlNzEtYmQ1Yi00NGU2LTgwOTgtM2ZlYzU1NjhmZTVj",
    "tls_client_auth" : false,

    "digest_hash" : "w0mymuL8aCrbJmmabs1pytZhon8lQucTuJMUtuKr+uw=",
    "digest_hash_algorithm" : "SHA256",
    "digest_payload" : "Z3JhbnRfdHlwZT1jbGllbnRfY3JlZGVudGlhbHM="
}

The Base64 decoded value of digest_payload is grant_type=client_credentials which is the actual payload from the bank.

As set in digest_hash the hashed value of digest_payload is w0mymuL8aCrbJmmabs1pytZhon8lQucTuJMUtuKr+uw= (the Base64 encoded representation of the binary hash value) which is also contained in the Base64 decoded payload of the request:

(request-target): post /oauth2/token
date: Wed, 31 Jul 2019 15:12:26 GMT
digest: SHA-256=w0mymuL8aCrbJmmabs1pytZhon8lQucTuJMUtuKr+uw=
x-ing-reqid: 66090e71-bd5b-44e6-8098-3fec5568fe5c

Response

{
    "signature": "VGhpcyBpcyBub3QgYW4gYWN0dWFsIHNpZ25hdHVyZSB2YWx1ZSE="
}

HSM Reverse API PIS Example

Request

{
    "session_id" : "175cnd9qoj7i9sh4ihf8ch8jrnc6th7t",

    "alias" : "klarna-qseal-2019-07-01",
    "algorithm" : "SHA256_RSA",
    "payload" : "ZGlnZXN0OiBTSEEtMjU2PVpUUUJONGtKWDJ3ZnhlMWJWbGtpck5FYVVINzkydGdoYmYwejJORTlUaHc9DQp4LXJlcXVlc3QtaWQ6IGYyZTRiMGI1LTg1MjQtNDU4My1hZDllLTJiNGU5MTRjMTUzMw0KcHN1LWlkOiBWUksxMjM0NTY3ODkwT1BUDQpkYXRlOiBUaHUsIDEgQXVnIDIwMTkgMDg6MTg6MjggR01U",
    "tls_client_auth" : false,

    "digest_hash" : "7Oh+5PoaHSDQzaby1LfXPFcN+5lT/UrsicJh9AlDj+w=",
    "digest_hash_algorithm" : "SHA256",
    "digest_payload" : "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/PjxEb2N1bWVudCB4bWxucz0idXJuOmlzbzpzdGQ6aXNvOjIwMDIyOnRlY2g6eHNkOnBhaW4uMDAxLjAwMS4wMyI+PENzdG1yQ2R0VHJmSW5pdG4+PFBtdEluZj48UmVxZEV4Y3RuRHQ+MjAxOS0wOC0wMSswMjowMDwvUmVxZEV4Y3RuRHQ+PERidHJBY2N0PjxJZD48SUJBTj5ERTQzMDAwMDAwMDA1Njg2NzUxMTY4PC9JQkFOPjwvSWQ+PC9EYnRyQWNjdD48Q2R0VHJmVHhJbmY+PEFtdD48SW5zdGRBbXQgQ2N5PSJFVVIiPjEyMzQ8L0luc3RkQW10PjwvQW10PjxDZHRyQWNjdD48SWQ+PElCQU4+REUxODAwMDAwMDAwNjYzNjk4MTE3NTwvSUJBTj48L0lkPjwvQ2R0ckFjY3Q+PFJtdEluZj48VXN0cmQ+dGhpcyBpcyBhIHRlc3QgcHVycG9zZSB0ZXh0PC9Vc3RyZD48L1JtdEluZj48L0NkdFRyZlR4SW5mPjwvUG10SW5mPjwvQ3N0bXJDZHRUcmZJbml0bj48L0RvY3VtZW50Pg==",
}

The Base64 decoded value of digest_payload is the following XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03"><CstmrCdtTrfInitn><PmtInf><ReqdExctnDt>2019-08-01+02:00</ReqdExctnDt><DbtrAcct><Id><IBAN>DE43000000005686751168</IBAN></Id></DbtrAcct><CdtTrfTxInf><Amt><InstdAmt Ccy="EUR">1234</InstdAmt></Amt><CdtrAcct><Id><IBAN>DE18000000006636981175</IBAN></Id></CdtrAcct><RmtInf><Ustrd>this is a test purpose text</Ustrd></RmtInf></CdtTrfTxInf></PmtInf></CstmrCdtTrfInitn></Document>

This is the actual payload from the bank.

As set in digest_hash the hashed value of digest_payload is ZTQBN4kJX2wfxe1bVlkirNEaUH792tghbf0z2NE9Thw= (the Base64 encoded representation of the binary hash value) which is also contained in the Base64 decoded payload of the request:

digest: SHA-256=ZTQBN4kJX2wfxe1bVlkirNEaUH792tghbf0z2NE9Thw=
x-request-id: f2e4b0b5-8524-4583-ad9e-2b4e914c1533
psu-id: VRK1234567890OPT
date: Thu, 1 Aug 2019 08:18:28 GMT

Response

{
    "signature": "VGhpcyBpcyBub3QgYW4gYWN0dWFsIHNpZ25hdHVyZSB2YWx1ZSE="
}

results matching ""

    No results matching ""