mTLS Callback Server Setup Guideline

Please note that setting up a trust-ca bundle is not necessarily required for your callback server, as the client should only be from the GTR server and not publicly accepted by others. This guide suggests having inbound request client cert validation to ensure GTR and your server both follow the mTLS spec.

All VASPs must set up a callback server to receive exchange information from another VASP. GTR will send HTTP or HTTPS requests to your callback server, and the protocol with the encrypted method depends on your callback URL provided in your login request (you can re-login to update the callback URL); if you provide 'http://', 'https://' will use the corresponding protocol to send the request.

In the scenario where you opt to secure your callback server using HTTPS, it's necessary to utilize a trusted request certificate list. This is typically called a Trusted Certificate Authority Bundle (ca_bundle). This can be sourced from the GTR website under the 'Create API Key' section. This results in a downloaded file with the name client-truststore.jks (or in .pem format).

The programming language in use on your callback server dictates the manner in which this file is used. Should you be utilizing Java (.jks), compatibility with Apache, GlassFish, Spring, etc. is assured. If using other languages, it may become necessary to convert the .jks file format to the .pem format. Please find below the script that assists with this conversion process.

Important considerations for your server:

It's pertinent to use your own certificate on your server. You can procure this from an external vendor. Please refrain from using public certificates such as 'Let’s Encrypt', as it may not provide optimum security. Please note that starting your server with certificate.pem downloaded from GTR isn't effective, as it doesn't function as required. The client-truststore serves as a whitelist, allowing the acceptance of incoming HTTP requests from GTR to your server. It's critical to maintain and update this list regularly for seamless server interactions.

• Tip: keytool command requires Java to be pre-installed on your system.

convert_jks_to_bundle.sh

#!/bin/bash
set -e

storepass="[paste store pass / client_store_password]"

while IFS= read -r alias; do
    keytool -export \
        -alias "${alias}" \
        -file "${alias}.crt" \
        -keystore client-truststore.jks \
        -storetype JKS \
        -storepass "${storepass}"

    openssl x509 \
        -inform der \
        -in "${alias}.crt" \
        -out "${alias}.pem"

    rm -f "${alias}.crt"
    cat "${alias}.pem" >> ca_bundle.pem
done < <(
    keytool -list \
        -keystore client-truststore.jks \
        -storetype JKS \
        -rfc \
        -storepass "${storepass}" \
    | grep "Alias name:" \
    | sed 's/Alias name: //'
)