# Payload Encryption
source: https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/api-basics/payload-encryption/index.md

The Payload Encryption feature is offered as an effective supplementary technical measure for securing the personal data of Payment Service Users (PSUs). This provides additional protection of PSUs' data in accordance with up-to-date EU/EEA standards.

By Using Payload Encryption, you will:

* Ensure that PSU's data remains protected if TLS is terminated by intermediaries
* Adhere to European Data Protection Board's requirement of key management control of TLS encrypted data

### Securing PSUs' personal data with Payload Encryption {#securing-psus-personal-data-with-payload-encryption}

All traffic to Mastercard Open Finance services is encrypted using industry standard Transport Layer Security (TLS). Whilst TLS itself is highly secure, in complex environments it is common for enterprises and cloud providers to have intermediaries (web application firewalls, network inspecting proxies, and others) to terminate TLS along the way.

Payload Encryption alleviates the risk of such intermediaries being able to access personal data, by encrypting the payload within the TLS stream at the application layer.

Payload Encryption answers the European Data Protection Board's (EDPB) requirement of key-management control of TLS encrypted data in transit in Microsoft Azure environment. The importance of Payload Encryption is enhanced by the fact that Microsoft Azure sub-processor potentially falls under the scope of FISA 702 as a cloud service provider.

Hardware Security Modules (HSMs) ensure the safe storage of our private keys. HSMs are tamper-resistant, tamper-evident hardware modules that only allow authenticated and authorized applications to use the keys. The key material never leaves the HSM protection boundary. Dedicated HSMs help meet compliance/regulatory requirements such as FIPS 140-2 Level 3, HIPAA, PCI-DSS and eIDAS, etc.

Using Payload encryption is optional and only enabled upon request from the client. This is to retain backwards compatibility and to keep the APIs developer friendly.

### Encryption keys {#encryption-keys}

When Payload Encryption is enabled, Mastercard will expect encrypted requests and encrypt all responses' payloads. Payload refers here to the request and response bodies of HTTP messages.

Payloads are encrypted using a hybrid RSA and AES model and packaged using the JWE Compact Serialization format specified in [RFC 7516](https://www.rfc-editor.org/rfc/rfc7516).

### Encryption and decryption process {#encryption-and-decryption-process}

* Both the client and the server manage their own RSA key pairs

* The payloads will be encrypted using AES in GCM mode

* The AES keys will be ephemeral and only used a single time

* The RSA keys are only used to encrypt the AES keys that will be used to encrypt each payload

As such, the full interaction between client and server with payload encryption enabled would be:

1. The client fetches the server's public key. It is recommended to cache it for up to 24 hours.

2. The client generates an ephemeral AES key and encrypts the body of the request with it.

3. The client encrypts the AES key with the server's public key.

4. The client assembles and sends a full request with the Request body encrypted and in the correct format [JWE Compact Serialization](https://www.rfc-editor.org/rfc/rfc7516#section-3.1) in a new tab and the `X-Payload-Encryption` header set with a Base64 URL Encoded version of JWK, prefixed by `clientPublicKey=`

5. The Server uses its private key to decrypt the AES key in the message.

6. The server uses the decrypted AES key to decrypt the request body and processes the request as normal.

7. The server generates an ephemeral AES key and encrypts the response body with it.

8. The server encrypts the AES key with the client's public key included in the `X-Payload-Encryption` header.

9. The server assembles and sends the response back in the same JWE format as before.

10. The client decrypts the AES key with its own private key.

11. The client decrypts the response body with the decrypted AES key.

The following diagram presents server public key discovery and how to make a request using payload encryption:

![Payload encryption diagram](https://static.developer.mastercard.com/content/open-finance-europe/uploads/payload-encryption-diagram_1.png)

### API specification {#api-specification}

#### Accessing the server public key {#accessing-the-server-public-key}

The server presents its latest public key at the following endpoint in the form of a JWK.

`GET /v1/payload-encryption-key`

Response:

```json
{
   "serverPublicKey":{
      "kid":"fd2201ccdfc346e4b219c88575fd3e09",
      "kty":"RSA-HSM",
      "n":"ymbBBIdIh8jeDFK[...]",
      "e":"AQAB"
   }
}
```

When Mastercard rotates its keys, it ensures to keep accepting the old public key for a period of time. It is recommended that the client caches our public key for up to 24 hours.

#### Making requests with payload encryption {#making-requests-with-payload-encryption}

Payload encryption is supported for all API endpoints that use JSON for requests and responses.
The API client enables payload encryption by setting the following header and specifying its RSA public key:

    X-Payload-Encryption: clientPublicKey=<base64 encoded JWK>

Example of payload encryption: Assume any JSON plaintext payload, e.g.:

```json
{ 
    "a": { "b": "..." } 
}
```

Then the encrypted payload will look like this:

```json
{
    "encryptedValue": "eyJlbmMiOiJBMjU2R0NNIiwia2lk[...]"
}
```

where the `encryptedValue` field uses [JWE Compact Serialization](https://www.rfc-editor.org/rfc/rfc7516#section-3.1) format:

```json
{ 
    "encryptedValue": "<JWE-header>.<encrypted-clientAesKey>.<iv>.<ciphertext>.<authTag>" 
}
```

### Error Handling {#error-handling}

If the request includes a valid `X-Payload-Encryption header`, the response should always be encrypted.

Errors returned when a Payload Encryption is active will be returned with a relevant status code and the error payload will be encrypted.

### Code Sample {#code-sample}

In order to see how you can integrate towards our products while using the Payload Encryption Feature, visit the following Github repository where a code sample written in C# is available:

<https://github.com/Mastercard-Samples/aiia-payloadencryption-sample-code>

### Threat model {#threat-model}

The payload encryption feature should not be seen as a replacement for TLS.

* It is meant to act as a supplementary technical measure to ensure customer's data confidentiality in the event of TLS termination by intermediaries like cloud providers

* It is not meant to protect against active attackers. Payload encryption alone will not protect against "replay attacks" or "Man in the middle attacks" (for example, during the request to get the server's public key)

* The client is responsible for creating and managing their own RSA and AES keys (for example, they should have enough entropy)