# TPP certificates
source: https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/production/tpp-certs/index.md

PSD2 APIs require Third Party Providers (TPPs) to use qualified eIDAS certificates. These certificates are used by the PSD2 APIs to verify the identity of the TPP, both as traditional client side certificates for mutual TLS, and for electronically signing data.
These certificates are used both for TPPs acting as Account Information Service Providers (AISPs) and TPPs acting as Payment Initiation Service Providers (PISPs).

Each TPP needs to acquire two certificates:

1. QWAC (Qualified Website Authentication Certificate) - For performing mutual TLS.

2. QSealC (Qualified electronic Seal Certificate) - For signing data.

Clients of Aiia Enterprise are TPPs. In order to access PDS2 APIs on behalf of the TPPs, Aiia Enterprise needs to have access to the TPPs' certificates.

## Acquiring {#acquiring}

There are several Qualified Trust Service Providers (QTSPs) that issue TPP certificates.

Every TPP needs to acquire both certificates, as PSD2 APIs require both.

Each certificate can handle both Account Information Service (AIS) and Payment Initiation Service (PIS), but it is important to specify that when ordering the certificates, as the roles are embedded within the certificates (and once the certificates are issued, adding roles requires buying new certificates, which is costly).

Be advised that TPP certificates expire. Before expiration, new certificates need to be acquired by you and installed by Aiia Enterprise. We ask customers to share the new TPP certificates no later than 30 days before the expiration date of the old certificates. TPP certificate installation fees apply.

The TPP needs to generate keys and submit a Certificate Signing Requests to their selected QTSP. See below for help on generating a Certificate Signing Request (CSR).

As QWAC certificates are also valid as TLS certificates for websites, we require that you specify the Common Name (CN) as well as Subject Alternate Name (SAN) to be

    yourname-com.aiiaclient.com

where `yourname-com` is based on your company domain, by replacing the dot with a dash. For example, if your domain is `example.com`, then you should use `example-com.aiiaclient.com`. Please let us know once you have ordered the certificate as the certificate issuer will require us to approve it (write to [openbankingeu_support@mastercard.com](mailto:openbankingeu_support@mastercard.com)). When chosing which email to validate the certificate on, please choose `hostmaster@aiiaclient.com`.

#### Generating the Certificate Signing Request {#generating-the-certificate-signing-request}

We recommend generating Certificate Signing Requests (CSR) using OpenSSL.   

You can generate a CSR using the following OpenSSL command:

    openssl req -new -subj "/C=DK/CN=example-com.aiiaclient.com" \
                     -addext "subjectAltName = DNS:example-com.aiiaclient.com" \
                     -newkey rsa:2048 -keyout key.pem -out req.pem -nodes

Command argument explanation:

    req                 : perform a command regarding CSRs
    -new                : specifies that a new CSR should be made
    -subj               : specifies the subject, C for Country Name, CN for Common Name
    -addext             : adds a CSR extension for DNS as outlined above
    -newkey             : specifies that a new private key with the RSA2048 encryption should be created
    -keyout <file name> : specifies that the generated private key should be saved into the specified file
    -out <file name>    : specifies that the CSR should be saved into the specified file
    -nodes              : specifies that the private key should be generated without a pass-phrase

We do not require a pass-phrase for the private key. If you prefer to include a pass-phrase, omit the `-nodes` parameter.

If needed, we can provide further advice on key generation and issuance of CSRs [Contact Us](https://openbankingeu.mastercard.com/contact-us).

**Background**   
The requirement to set hostname on QWAC certificates is somewhat confusing, as this is a requirement for *TLS server certificates* , whereas QWAC certificates are *TLS client certificates*. (When doing mutual TLS authentication there is no concept of a hostname for the client, only for the server.) This is however a technical requirement for QWAC certificates and thus issuers need to ensure it is followed. Furthermore, some Account Servicing Payment Service Provider (ASPSP) have indicated that they might in the future use the hostname specified in the QWAC for validation, which is why the certificates need to point to valid endpoints that Aiia Enterprise can control.

#### Links {#links}

* [List of QTSPs from Open Finance Europe](https://www.konsentus.com/qtsps-and-eidas/)

## Installation {#installation}

Once certificates have been acquired, they need to be made accessible to Aiia Enterprise.

TPP certificates consist of a private key and the actual certificate. Aiia Enterprise handles these two parts separately. The actual certificate, which is public, is stored by Aiia Enterprise in our key configuration.

For the private key, Aiia Enterprise offers two options:

#### 1. Aiia Enterprise hosts the private key {#1-aiia-enterprise-hosts-the-private-key}

Aiia Enterprise stores the private key in its key configuration. The key is stored strongly encrypted and only used when communicating on behalf of the client. This is an efficient and safe approach which does not require any setup on behalf of the client. Furthermore, this ensure high performance of performing cryptographic operations.

When managing keys, the keys are asymmetrically encrypted in our key configuration, so that keys are not accessible to any other system than Aiia Enterprise's Core system, which performs communication with banks.

##### Setup {#setup}

1. Coordinate an appropriate secure channel with Aiia Enterprise technicians and share certificates through this channel. PFX and/or PEM formats are preferred.

2. Aiia Enterprise technicians install the certificates, including encrypted private keys, into our configuration store.

3. Aiia Enterprise technicians verify that the certificate works, by initiating sessions towards one or more PSD2 APIs.

#### 2. The client hosts the private key {#2-the-client-hosts-the-private-key}

Aiia Enterprise supports using private keys from [Azure Key Vault](https://azure.microsoft.com/en-us/services/key-vault/), which is a key management solution from Microsoft. With this option, the private keys are fully controlled and managed by the client and not directly accessible by Aiia Enterprise.

The client is in full control over the private keys, and only needs to grant Aiia Enterprise access to perform the sign cryptographic operation using the keys.

This diagram depicts the setup and data flow:

![Azure Key Vault Setup](https://static.developer.mastercard.com/content/open-finance-europe/uploads/keyvault-diagram.svg)

##### Implications of client hosted keys {#implications-of-client-hosted-keys}

This method has a small negative impact on performance. This overhead does not count towards the request time SLA. Typical performance impact is listed below.

| **Percentiles** | **50** | **95** | **99** | **99.9** |
|-----------------|--------|--------|--------|----------|
| Milliseconds    | 37     | 98     | 239    | 3369     |

Also note that this adds management overhead for the Client and requires that the Client can provision resources on Azure.

##### Setup {#setup-1}

1. Provision Azure Key Vault(s) and install the certificates into it (see below).

2. Coordinate an appropriate secure channel with our technicians and share access credentials to the Azure Key Vault and key URLs through this channel.

3. Share the TPP certificates (excluding private keys) with our technicians. Preferred format is PEM. (This can be done through insecure channels, e.g. email, if needed.)

4. Our technicians install the certificates, together with credentials for Azure Key Vault and key URLs into Aiia Enterprise's configuration store.

5. Our technicians verify that the certificates and keys work, by initiating sessions towards one or more PSD2 APIs.

##### Provisioning Azure Key Vault {#provisioning-azure-key-vault}

The Client is responsible for provisioning Azure Key Vault and installing keys into it.

Aiia Enterprise needs two pieces of information to use keys in Azure Key Vault:

1. Credential to access the Key Vault: Access to Azure Key Vault is granted through a Service Principal, which has a Tenant ID, App ID and Password. These credentials need to be shared with Aiia Enterprise, so that Aiia Enterprise can access the Key Vault.

2. URLs to the keys: For each certificate (QSealC and QWAC), Aiia Enterprise needs the URL to the keys. Azure Key Vault issues a unique URL to each key.

Below is an example of how to create an Azure Key Vault using the Azure CLI, import a private key into it, and to create a Service Principal for allowing Aiia Enterprise to access. (This can also be done manually in the Azure Portal.)

```shell
# Create a resource group and a Key Vault instance. 
# Names of the resource group and the Key Vault is fully up to the TPP.
> az group create -n tpp-vault-demo -l northeurope
> az keyvault create -g tpp-vault-demo -n tpp-vault-demo

# We assume that we have the private key for QSealC in qsealc-private-key.pem.
# We import that to the Key Vault (insert your own PEM password), with the name
# "qsealc":
> az keyvault key import --vault-name tpp-vault-demo \
    --pem-file qsealc-private-key.pem -n qsealc \
    --pem-password <PEMPASSWORD> --ops sign
{
  "attributes": { ... },
  "key": {
    ...
    "kid": "https://tpp-vault-demo.vault.azure.net/keys/qsealc/c176973d11f44f029193d8a33f0a0617",
  }, ...
}

# The import above is repeated for each key (QSealC and QWAC).
# Note the URL in the "kid" field: Share this with Mastercard Open Finance for each key.

# We now create a Service Principal, which is a application registration in Azure,
# containing credentials that can be used to connecting to the Key Vault. 
> az ad sp create-for-rbac --name tpp-vault-demo-access-for-nag --skip-assignment
{
  "appId": "898be14f-d4f7-4bd8-9134-c8a64431a097",
  "displayName": "tpp-vault-demo-access-for-nag",
  "name": "http://tpp-vault-demo-access-for-nag",
  "password": "e81c3ba6-e9a6-4bca-8bbf-b1cbdf6a4082",
  "tenant": "cffca3e4-dc9c-4985-b867-85c56026f354"
}

# Finally, we create an access policy on the Key Vault, granting the Service Principal 
# access to perform signing operations using keys in the Key Vault. The principal name
# sent to --spn comes from the output from above:
> az keyvault set-policy --name tpp-vault-demo --key-permissions sign \
    --spn "http://tpp-vault-demo-access-for-nag" -g tpp-vault-demo

# Note: The Service Principal only needs to have the sign permission, as shown above.
```

##### Further reading {#further-reading}

[Logging access to Azure Key Vault for auditing](https://docs.microsoft.com/en-us/azure/key-vault/key-vault-logging)

## UK certificates {#uk-certificates}

Customers that are registered TPPs for account information services (AIS) and payment initiation services (PIS) in the UK will need to enrol with the Open Banking Directory.

To start the process, you need the following:

* Access to the [Open Banking Directory](https://directory.openbanking.org.uk/s/login/)
* Request permission from Open Banking to access the "Directory"
* URL to your Terms and Conditions
* URL to your Privacy Policy
* URL to your company logo
* Your company's website URL
* The redirect URI - this will be the same redirect URI registered with Aiia Enterprise

Once you are set up with Open Banking Directory, you need additional instructions to set up registrations with certain ASPSPs:

1. Create an Open Banking Software Statement
2. Register with specific ASPSPs via their developer portals
   * [Barclays](https://developer.barclays.com/login)
   * [Santander](https://developer.santander.co.uk/sanuk/external/)
3. Once you completed, please send the following to us:
   * The Client ID and Secret of ASPSP applications created with Barclays and Santander
   * Software Statement ID
   * The redirect URI - this will be the same redirect URI registered with Aiia Enterprise

## Certificate renewal {#certificate-renewal}

Open Banking certificates are valid for 1-2 years. When the certificates are due for renewal, you will need to perform processes such as domain control validation and authorized representative validation. Your issuing QTSP will notify you some weeks prior to the expiry date with specific instructions on renewal. If the Common Name (CN) changes during renewal, new registrations with some ASPSPs may be necessary.

We recommend that TPPs complete the renewal process well ahead of time. ASPSPs have varying processes to onboard the renewed certificates and normally needs to be registered on the developer portal before use.

The TPP is responsible for renewing and providing the certificates to Mastercard 45 to 60 days prior to the expiration date.