Connectivity overview

All APIs exposed by Thales require to go TLS mutual authentication, this is valid for incoming as well as for outgoing API from Thales.

TLS connectivity setup is the first step of the setup and it needs to be performed before the configuration of the Thales services. The Tokenization Service has a unqiue endpoint for all APIs. It means that TLS connectivity setup is done only once for all Thales services.

As a consumer of the APIs, you are known as a "customer" or "actor" and as such you have a customer identifier within Tokenization Service. This identifier is important because the TLS connectivity is setup individually for each customer identifier.

TLS connectivity must be establish explicitely for each environment, each of them being isolated :

• Pre-production

• Production

Incoming Flow from your host to Thales TSH

Endpoint	Environment
https://api.dbp-stg.thalescloud.io	Pre-Prod
https://api.dbp.thalescloud.io	Prod

You will require the Thales CA to sign your TLS client certificate in order to access the TSH API. To do this, you will have to provide a Certificate Signing Request (CSR) to your Thales representative for signature.

General requirements:

1. Algorithm: RSA encryption with 4096-bit or ECDSA P-256 keys and SHA256 hashing.

2. Common Name (CN): format and value are enforced and checked by Thales. The value should follow the pattern described in step 2 of the example below.

Example CSR Generation

Repeat the following procedure for each one of the environments you target; pre-production and production.

1. Generate a new key pair for your CSR either RSA or ECDSA.

You can create a RSA 4096 key pair with the following OpenSSL command:

openssl req -new -newkey rsa:4096 -nodes -keyout private_rsa.key -out issuer_pp.csr -subj "/C=<Country>/ST=<State>/L=<Locality>/O=<Issuer Organization>/OU=<Issuer Organization Unit>/CN=TLSMA-RSA\/<tspId>\/TSH\/TSP.<env>"

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

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

where:

• country means issuer country.

• state means issuer state.

• locality means issuer localitity.

• Organization Name must be the issuer organization name.

• Organizational Unit must be the issuer organization unit.

• CN means Common Name.

• tspId is the id provided to you by your Thales representative.

• env is the environment targeted by this certificate. For pre-production: PPR, for production: PRD

• ECDSA vs RSA in CN depends on key type.

The issuer backend must systematically resolves the TSH domain name and its subdomains. Thales TSH doesn’t support long term static IPs and for this reason, Thales customer must never configure, hardcode, or cache TSH IP addresses for a period higher than the Time To Live returned by the Domain Name Server.

Outgoing Flow from Thales TSH to your host

General requirements:

1. Mutual Authentication

2. TLS 1.2 (or higher)

3. Your server must run on port 443 (or 8443, but 443 is preferred)

4. Over the internet (no IP whitelisting)

5. You must trust Thales Client CA to authenticate our client certificate. Our Client CA is available for download from our TSH Portal for Issuer and manually exchanged for Merchant. If required, Thales can generate a new key pair to be signed by the TSP.

6. Thales TSH must trust your server certificate, for this you must provide your server CA Chain to be endorse through our TSH Portal for Issuer and manually exchanged for Merchant.

You must endorse only our Client CA, and you must not "pin" the client certificate. Our client certificate are signed by our Client CA. TSH may rotate its client certificate any time before their expiry date without notice to you.