Create API Key and mTLS Certificate

mTLS (Mutual Transport Layer Security)

mTLS is employed by GTR to safeguard client requests to the API Server. This involves both parties verifying each other's certificates. To obtain your certificate, you'll need to generate the Certificate Signing Request (CSR) on your local computer, upload it to GTR, and procure the signed certificate.

API Secret Key

To access the GTR API Server, you'll need to generate the token using the API Secret Key. We combine the mTLS certificate and API Secret Key into a single compressed file. When you submit your CSR and create an API key, you'll download this file, extract it, and securely store it in the vault.

Here are the steps to create an API Key and mTLS certificates:

1. Create Key Pair and Access Keys

1. Visit the website: https://www.globaltravelrule.com.
2. Navigate to: [My Account] > [API Info] in the [API Key (Security Credential)] section.
3. Click on [Create API Key].

Before get access to verify server, it is required to have mTLS connection and access/secret key, you must to save the these keys to the vault carefully, letting the developer using vault to get the access token, and make sure the HTTP client are using mTLS connection, which means each connection brings the client certificate public key to GTR service. (it is must to have private/public key to send the request by using the client certificate)

2. Create a Key Pair on your computer (CSR)

We use your certificate signing request file (CSR) to make the signature of GTR's public key, CSR describe your organization info to identify and sign by using your private key, therefore you only need to given the CSR to GTR and get the public certificate, and using your pair private key to decrypt, GTR doesn't involves to your private key to keep safe.

Before initiating the creation of an API Key, ensure to generate a Certificate Signing Request (CSR). Be certain OpenSSL is installed in your environment. You can then generate your CSR by following the shell commands provided below. (After putting it into the terminal and executing it, it will enter interactive mode. Please answer according to the actual situation and complete the file generation.)

openssl req -new -newkey rsa:4096 -nodes -keyout PRIVATE.key -out CSR.csr

For your subject fields, provide information as follows: 'C' for Country code, 'ST' for State, 'L' for Location, 'O' for Organization, and 'OU' for Organizational Unit. Please ensure that these fields are populated correctly and are applicable to your company. For the 'CN' field, or Common Name, input your domain name (for instance, 'sub.example.com'). The 'CN' will be used to identify the domain where you enable the callback service, please double confirm the domain is mapping to your callback server..

When completing your subject fields, ensure the following information is provided accurately and that it aligns with your company's details:

• 'C' stands for Country code. (Location / Country with 2-alphabet)
• 'ST' represents the State. (Location / State)
• 'L' is for the Location. (Location / City)
• 'O' denotes the Organization. (Your organization name)
• 'OU' stands for Organizational Unit. (Your business unit)
• 'CN' stands for Common Name. (Your domain name)

In the 'CN' field, or Common Name, input your domain name (e.g., 'sub.example.com'). The 'CN' field is used to identify the domain where the callback service is activated, hence it is crucial to double-check the domain is correctly mapped to your callback server.

Once you've completed these aforementioned procedures, you will have generated two important elements: A private key, which is referred to as 'PRIVATE.key' and a CSR, labeled as 'CSR.csr'. The 'CSR.csr' file will be essential for the subsequent step.

Proceed by clicking on the 'Create API Key' button. This is where you will attach the CSR, enter your domain name, and specify the client-truststore format before clicking 'Next'. Doing so will generate an access key, a security key, and a public certificate for your server, the latter being designated as 'certificate.pem'. Kindly follow the steps outlined by the on-screen prompts as you proceed from this stage.

If you wish to use a command that directly generates a CSR, you can prefill all parameters into the parameters.

openssl req -new -newkey rsa:4096 -nodes -keyout PRIVATE.key -out CSR.csr -subj "/C=US/ST=California/L=San Francisco/O=OrganizationName/OU=IT Department/CN=[Your Domain Name]/emailAddress=contact@example.com"

Upon successful completion of the steps, you will be able to download the file key_and_certificate.zip.

The generation of the API key by the GTR server may take a while. Once generated, the new API key will be automatically downloaded to your system.

• Should the API key not download automatically, you have the option to manually download it by clicking the "Download Key" button.
• It is critical to store your API keys securely. Please remember that each company is limited to creating only one access key every 24 hours.

The generation process for both the access key and secret key adheres to a set of predetermined rules:

• Access Key: This is created by a randomized string adhering to the pattern ^[A-Z1-9]{64}$.
• Salt: This is a randomly generated string following the pattern ^[A-Z1-9]{16}$.
• Secret Key: Similar to the others, the secret key is a randomized string that follows the pattern ^[A-Z1-9]{256}$.

Please note, each account is permitted to have only one API key at any given time. Whenever a new API key is generated, the previous access key and secret key will be instantaneously invalidated. Therefore, it's crucial to keep a record of the newly created API key, as the old one becomes obsolete.

3. Submit the CSR and download Key Files

Upon successfully obtaining your signed certificate from the GTR (Global Travel Rule) Website, you can proceed to access the contents of the key_and_certificate.zip file. Upon extracting this file, you will find it consists of the following three components:

key_and_certificate.zip
├── api_key.csv
├── certificate.p12
└── client-truststore.jks

• certificate.p12: This file contains the mTLS certificate for any HTTPS request sent to the GTR server, including login procedures.

  Important: This file is not for starting your server. Please refrain from using it for such purposes.

• client-truststore.jks: This file is the client-trust Certificate Authority (CA) bundle, providing the whitelist client certificate. You may need to use this certificate to verify incoming requests from the GTR server.

• certificate.pem: This file houses the HTTPS certificate that is deployed by the business service when it initiates HTTPS requests to the GTR API.

  Note: See the following steps for instructions on using this file to send an mTLS request.

• client-truststore: This file serves as the HTTPS service trust store, which business services utilize to receive GTR callback responses.

  Note: This file does not require a password. If a password prompt appears, leave the field empty.
  Important: Do NOT use this file to send requests. This certificate is exclusively for receiving GTR callbacks to your server.

• api_key.csv: This document stores the access_key and secret_key.

4. Make key pair format - create .p12 or .jks for your server

There are several scenarios for using mTLS certificates in different formats:

1. Directly usage of certificate.pem and private.key

   This method involves starting your server with these keys directly. However, it's important to note that the private key is not password-protected, which could pose a security risk.

2. PKCS12 - New

   To consolidate your private key and signed certificate into a .p12 file, follow the guidelines outlined below:

   openssl pkcs12 -export -out certificate.p12 -inkey PRIVATE.key -in certificate.pem -passout pass:[YOUR PASSWORD OF CERTIFICATE]

   Following these instructions accurately ensures the preservation and protection of your sensitive data, ultimately fostering an environment of secure and encrypted communication with the GTR server.

   With the successful acquisition of the .p12 format certificate, you are now well-equipped. Please proceed to the section titled 'Prerequisites' to understand the process behind making a login request.

3. PKCS12 Legacy Java

   Using a legacy version of Java, specifically versions earlier than 8u301 or 11.0.1, may not allow for the direct use of the openssl command provided above to run your server. This limitation arises because the openssl command uses the PBE2 cipher, which is not handled correctly by the mentioned versions of Java.

   Please refer to the following commend:

   openssl pkcs12 -export -out certificate.p12 -inkey PRIVATE.key -in certificate.pem -passout pass:[YOUR PASSWORD OF CERTIFICATE] -legacy

4. JKS:

   To bind your private key and signed certificate into a .jks (Java KeyStore) file, follow these specific steps:

   openssl pkcs12 -export -in certificate.pem -inkey PRIVATE.key -out keystore.p12 -name gtr_keypair -passout pass:[YOUR PASSWORD OF CERTIFICATE]
   
   keytool -importkeystore -destkeystore keystore.jks -srckeystore keystore.p12 -srcstoretype PKCS12 -alias gtr_keypair -deststorepass [YOUR PASSWORD OF CERTIFICATE]  -srcstorepass [YOUR PASSWORD OF CERTIFICATE]

Upon the successful execution of these instructions, you will have the 'certificate.jks' file in your possession.

The .jks file format is proprietary to the Java platform. If you're employing a different programming language, for instance, Python, you will need to transform the file format into PEM. Please refer to Appendix I for a detailed step-by-step guide on how to accomplish this file format conversion to PEM and to effectively establish a mTLS server.