About mTLS

About Access Key and Secret Key

The Access Key and Secret Key serve as the connecting bridge between your server and the GTR central server. The Access Key is responsible for identifying the account associated with the incoming request, while the Secret Key authenticates the Access Key to confirm its validity.

To boost security, customers are encouraged to generate their own Private Key and Certificate Signing Request (CSR) File within their own environment. The CSR (which contains the public key and identity) is then submitted to GTR for the signature process. After the signature process completes, GTR returns the .PEM certificate (the Public Key/Signed Certificate) to the customer.

On obtaining the .PEM certificate and alongside their privately held key, customers can initialize their server with mutual TLS (mTLS). The detailed steps involved in setting this up are explained in the following section

Create Access Key and Secret Key

Generating an access key and secret key is a straightforward process. To begin, you need to log into the GTR website and navigate to the

API Info Page.

• The system requires both email and 2FA (Two-Factor Authentication) verification codes to further proceed. If 2FA verification hasn't been set up on your account, please refer to our guide on Config 2FA for instructions on how to register 2FA verification.

There are two types of user categories to consider when creating API keys: Trial User and Professional User.

• Trial User: Trial users are provided limited access to API key functionalities.
  • They are unable to generate or utilize API keys while their user status is "Under Review" or marked as "Rejected."
• Professional Users: Professional users have complete access to API key functionalities unless their status is "Under Review" or "Rejected."
  • If a user has already been approved as a Trial User, they can utilize API keys with functionalities limited to trial user level.
  • Users previously approved as Trial Users can choose to continue using their old API key or create a new one.

Here are the steps to create an API Key:

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 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.

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"

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.
• 'ST' represents the State.
• 'L' is for the Location.
• 'O' denotes the Organization.
• 'OU' stands for Organizational Unit.

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.

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.

Acquiring Your Signed Certificate from the GTR Website

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.

Requesting a Certificate

Typically, the use of certificate.pem and your PRIVATE key is mandatory when dispatching a request. However, if you're utilizing tools like Postman, cURL, Python, or Java to make a request, we suggest creating a .p12 file. This is a key-pair file that merges your signed certificate (certificate.pem) and private key (PRIVATE.key), securing both with a password of your choosing.

Certain services may favor using .p12 or .jks file extensions for extra convenience. As our provision is limited to signed public certificate Certificate Signing Requests(CSRs) in PEM format, you might need to generate .p12 or .jks files. For such cases, consider the guidelines mentioned below. (For generating a .jks file, please proceed to the next section)

Remember, generating these files ensures that your digitally signed certificates and private key stay paired and secured, bolstering the safe, encrypted communication between your system and the GTR server.

In the quest to consolidate your private key and your signed certificate into a .p12 file, follow the guidelines as necessitated 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 promoting 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 chapter titled 'Prerequisite’ to understand the process behind making a login request.

Certificate Format Advice (for .JKS):

To bind your private key and signed certificate into a .jks 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.

Others

For a secure connection to exist between a business service and the GTR (Global Trade Repository) server, it is essential for each entity to possess a mutually recognized and trusted certificate, enabling efficient interaction via RESTful API.

Business services necessitate the ownership of a GTR-issued certificate to establish a connection and facilitate interaction with the GTR server.

• Upon initiation of an SSL connection by a business service, a P12 certificate, generated via the "Generate API Key" function, is loaded. The associated secret key serves as the password for this certificate.
• As the business service initiates the HTTPS service for interaction with the GTR server, it is required to load a trust store specifically for trusted connections to the GTR server. This trust store is issued via the "Generate API" function, thereby enabling verified secure connections. The corresponding password for this trust store is generated and kept in a CSV file.

Download file including

• The certificate.pem is an HTTPS certificate employed by the business service when initiating HTTPS requests destined for the GTR API.
• The client-truststore serves as the HTTPS service trust store utilized by business services when receiving callback responses from the GTR. This file does not contain a password. Therefore, if a password prompt appears, simply enter nothing or leave the field empty.
• The api_key.csv is the file designated for storing the access_key and secret_key.

Begin the process of launching your callback server by utilizing the mTLS certificate.

• The mTLS certificate client-truststore.jks houses the array of trusted certificate fingerprints. These are crucial in enabling your service to authenticate incoming traffic from the GTR. Proper configuration of this feature is vital for your integration.
• 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.