> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/transit-digitization/integrate-d1-transit-api/set-up-tls-mutual-authentication.md).

# Set up TLS mutual authentication

All APIs exposed by D1 Transit server require TLS mutual authentication, this is valid for incoming as well as for outgoing API calls from D1 Transit server.

As a consumer of D1 Transit APIs, you are known as an "**issuer**" and as such you have an **issuer identifier** assigned within D1 platform. This identifier is important because the TLS connectivity is setup individually for each **issuer identifier**.

There are two D1 environments, pre-production and production, which are isolated from each other. You need to establish TLS connectivity explicitly for each one of them.

### Flow from Transit Issuer to Thales <a href="#flow-from-transit-issuer-to-thales" id="flow-from-transit-issuer-to-thales"></a>

<figure><img src="https://1928701359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZoFRCpZeaDWwcHYhJY7B%2Fuploads%2FkfY3xtjVQEpXG39LsJSh%2Fimage.png?alt=media&amp;token=1bcb0159-3b4d-45df-88df-8c970c92c6f5" alt=""><figcaption></figcaption></figure>

General requirements:

1. Mutual Authentication
2. TLS 1.2+ (TLS 1.3 is preferred)
3. Over the internet

{% hint style="info" %}
Thales applies IP Whitelisting
{% endhint %}

4. Thales server CA: signed by Amazon CA
5. Transit issuer client certificate: signed by the Thales CA

**Client Certificates**

You have to request the Thales CA to sign your TLS client certificate in order to access the D1 Transit APIs. To do so, you have to provide a Certificate Signing Request (CSR) to your Thales representative for signature.

**General requirements:**

1. Algorithm: ECDSA P-256 keys and SHA256 hashing.
2. Common Name (CN): format and value are enforced and checked by Thales. The value shall follow the pattern described below.

**Example CSR Generation**

* Generate a new key pair for your CSR ECDSA type.

You can create an ECDSA P-256 key pair with the following OpenSSL commands:

```bash
openssl ecparam -name prime256v1 -genkey -noout -out d1-mtls-client-cert.key
openssl req -new \
-key d1-mtls-client-cert.key \
-out d1-mtls-client-cert.csr \
-subj "/C=<country>/ST=<state>/L=<locality>/O=<Issuer Organization>/OU=<Issuer Organization Unit>/CN=TLSMA-ECDSA\/<issuerId>\/TSH/TRANSIT.<env>"

```

Where:

* *Organization Name* must be the issuer organization name.
* *Organizational Unit* must be the issuer organization unit.
* *CN* means Common Name.
* *issuerId* is the id provided to you by your Thales representative.
* *env* is the environment targeted by this certificate. For test environment: `REL/QA1`, for pre-production: `PPR`, for production: `PRD`

{% hint style="info" %}
The Transit issuer backend must systematically resolves Thales D1 domain name and its subdomains. Thales D1 platform doesn't support long term static IPs and for this reason, Thales customer must never configure, hardcode, or cache IP addresses for a period higher than the Time To Live returned by the Domain Name Server.
{% endhint %}

### Flow from Thales to Transit Issuer <a href="#flow-from-thales-to-transit-issuer" id="flow-from-thales-to-transit-issuer"></a>

<figure><img src="https://1928701359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZoFRCpZeaDWwcHYhJY7B%2Fuploads%2FUtfcuxHXAi3QKKeseltN%2Fimage.png?alt=media&amp;token=00a33d78-4054-4f78-b6cf-43dcc4f2fd2b" alt=""><figcaption></figcaption></figure>

#### General requirements: <a href="#general-requirements-2" id="general-requirements-2"></a>

1. Mutual Authentication
2. TLS 1.2+ (TLS 1.3 preferred)
3. Over the internet

{% hint style="info" %}
Thales applies IP whitelisting
{% endhint %}

4. You must either trust the Thales Client CA to authenticate the MTLS client certificate presented by Thales D1 platform (The Thales Client CA will be shared with you during the onboarding process) OR you must provide your client CA chain during the onboarding process
5. Thales D1 platform will trust your server certificate. For this you must provide your server CA chain during the onboarding process.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.payments.thalescloud.io/transit-digitization/integrate-d1-transit-api/set-up-tls-mutual-authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.