4.1 Setting Up EHI with mTLS

This section describes how to set up the External Host Interface (EHI) to communicate with Thredd using Mutual Transport Level Security (mTLS). This involves:

1. Setting up both server and client certificates for the mTLS connection.
2. Testing the certificates to prove the establishment of the mTLS connection.

To find out where mTLS exists in the network infrastructure between Thredd and your EHI endpoint, refer to background information in Message Architecture Between Thredd and EHI . For information on boosting security in the mTLS setup, see Additional Security Controls.

4.1.1 Overview of mTLS in EHI

mTLS is used where both parties must prove their identities to each other for authentication, in this case Thredd and yourself, the Client. The server and the client present their respective certificates and private keys to verify who they claim to be. The high-level communication flow is as follows:

1. The client (Thredd) connects to the server (you, the Client)
2. The server (you) presents your certificate.
3. The client (Thredd) verifies your certificate.
4. The client (Thredd) presents their certificate.
5. The server (you) verifies the client's certificate.

Once both certificates are verified, the server grants access. The client and server then exchange information over the secure connection.

mTLS relies on a system of digitally signed certificates issued by a trusted third party called a certificate authority (CA). The CA proves the authenticity of the public key and the identity of the server presenting the key. In addition to the server certificate, you also needs to have root and leaf certificates for validation. This ensures that a Chain of Trust is established. For a more detailed description on mTLS, refer to the descriptions on the CloudFlare website.

4.1.2 Set Up Certificates on the Server

You first need to set up the server certificates on your EHI server. The EHI server validates the client certificates that Thredd sends to you.

1. Obtain a Server Certificate from a Certificate of Authority vendor, such as Verizon or Digicert or Amazon Web Services.
2. Install certificates on your EHI listening endpoint. The certificates are as follows:

• Server or Leaf Certificate — this certificate is issued to individual servers by a CA. This certificate provides the “leaf” of a hierarchical tree of authority that’s traceable to the trusted root certificate.
• Intermediate or Issuing Certificate — this is a digital representation of a computer's identity in the PKI system, containing the public encryption key of the system, the purpose of the certificate, the identity of the issuing Certificate Authority, the validity period, and the bearer's name and digital signature.
• Root or CA Certificate — this enables an organisation to be their own Certificate Authority. This certificate also contains the public key. Typically, the certificate is installed on the server.

4.1.3 Store the Client Certificates

As Thredd sends you a Client Certificate, your server verifies the incoming certificate by matching it against the information held in Thredd's Certificate Authority’s Root and Issuing Certificates. You need to store the CA's Root and Issuing Certificates on your mTLS termination point. The steps for storing depend on your CA Vendor. For example, the steps may differ if your vendor is Alibaba Cloud or AWS.

The mTLS termination point is part of the infrastructure that manages the mTLS communication, and is where the certificates are stored.

The following are the Sandbox Certificates for UAT

The following are the Production Certificates

4.1.4 Testing the EHI Endpoint

Once you have set up your EHI endpoint with mTLS, you should test the endpoint with the online SSLLabs tool and OpenSSL. This is to ensure that you can successfully communicate with EHI over mTLS. Once you have completed testing, provide the EHI endpoint to Thredd.

You must not provide the EHI endpoint if you have not completed testing.

Test Using SSLLabs

1. Go to the URL of the tool: https://www.ssllabs.com/ssltest/.
2. Enter the URL to be tested in the SSL Labs test screen test page. The results appear similar to the following:

Figure 8: Passing Tests on SSL Labs

An “A” Grade results in the test passing. However, “B” will not result in a pass, and can indicate that the problem is due to a missing an Immediate or Root certificate on your server.

Test Using OpenSSL

You run the following command that triggers the TLS Handshake for the communication between server and the client. You receive responses for the server and client certificates.

openssl s_client -connect ehi.yourdomain.com:443

Server Certificate Result

The results for the server certificate appears as follows:

Figure 9: Server Certificate Result Including Depth Settings

If Depth 0,1,2 all show verify return:1 this indicates that the EHI servers trust the TLS endpoint / Server Certificate. There could be an issue with server certificate result, if the results appear differently, for example, there is no verify return:1 for the depth settings. The Depth settings mean the following:

You should configure your server’s TLS setup so that it sends the Server Certificate and the Intermediate Certificate. If the server sends only the Server certificate the Chain of Trust is not complete, which results in the mTLS not being set up between the server and the client.

Client Certificate Result

For validating the Client Certificate, certificates used by Thredd appear under Acceptable client certificate CA names. An issue may exist if the Acceptable client certificate CA names section is empty, where there Thredd's CAs are not listed.

Figure 10: Client Certificate Response

Listing the CA authority is optional. If this is empty, it may not mean that the mutual part of the certificate validation has failed.

You may need to check the EHI listener endpoint configuration if the following has occurred:

• If the SSLLabs test does not give an A Grade Response
• the Server Certificate does not show verify return:1 at all depths

• the Acceptable client certificate CA names are not sent

Testing Requests Without a Certificate

For additional testing, you can test a request to the EHI endpoint that does not contain a certificate. Using cURL, you see a 400 or 403 response as in the following example.

# Request 
curl -v https://api.yourdomain.com/ehim/endpoint/api
# Partial Response 
<html>
<head><title>400 No required SSL certificate was sent</title></head>
<body>
<center><h1>400 Bad Request</h1></center>
<center>No required SSL certificate was sent</center>

Testing Requests With a Certificate

You can also test a request to the EHI endpoint that contains a certificate. Using cURL, you see a 200 response as in the following example.

# Request 
curl --cert ./exampleClientCert.pem --key ./exampleClientCert.key \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"foo": "bar"}' \
     -v https://api.yourdomain.com/ehim/endpoint/api
# Partial Response 
200 OK

4.1.5 Message Architecture Between Thredd and the Customer EHI

The following shows the message architecture between Thredd and Thredd and your EHI components (the EHI Customer). The EHI listener endpoint and the mTLS termination point are part of your EHI components.

Figure 11: Message Architecture Between Thredd and EHI

1. Thredd uses the Certificate Authority, Thredd Certificate Authority, to create a Transport Certificate to enable communication later over mTLS.

2. Thredd's Message Processor sends and processes EHI messages that are received from the Cards Schemes (Networks) to Thredd's EHI servers.

3. Thredd sends the EHI messages via a gateway and adds the Transport Certificate.

4. EHI requests travel across the Internet with the associated Transport Certificate attached. Note that Thredd's outgoing firewall has a fixed IP address.

5. The Transport Certificate is presented to the customer's incoming mTLS termination point during the connection handshake.

6. Your systems validate the Transport Certificate by checking it against the CA chain of trust (Root and Issuing Certificates).

7. When the mTLS handshake is complete, you receive EHI messages on your EHI endpoint (External Host System).

4.1.6 Adding Security Controls

You can choose to implement additional optional controls to enhance mTLS security. These include the:

• IP Address Allow List — Thredd EHI messages are sent from a firewall with a fixed IP. Optionally, you can add this IP to your Allow List.

• Certificate Pinning — Whilst our mutual communication is secured by our Transport Certificate which is only trusted if it has been issued by our CA, you can choose to also implement Certificate Pinning. Certificate Pinning blocks attempted requests made with the incorrect certificates. For more information, see Certificate and Public Key Pinning | OWASP Foundation.