Setting up EHI for TLS connections and signed payloads

The External Host Interface (EHI) offers a way to exchange transactional data between the Thredd processing system and the Program Manager's externally-hosted systems. All transaction data processed by Thredd is transferred to the external host system via EHI in real time.

EHI provides two main functions:

• a real-time transaction notification data feed

• payment authorisation control

Follow these steps to set up the External Host Interface (EHI) to communicate with Thredd using TLS and signed payloads.

Configuring your Server to use EHI with signed payloads

Summary of the steps you need to complete:

1. Obtain a Server Certificate from a Certificate Authority (CA) vendor and install the certificate on your EHI listening endpoint.

2. Log in to Thredd Portal and download the Authentication Certificate.

3. Implement signature validation logic.

4. Test your EHI endpoint for TLS communication.

5. Provide the EHI endpoint to Thredd and inform Thredd that you are ready to use the EHI application.

Prerequisites

• You must have the Organisation Admin role for your organisation in Thredd Portal.

• You must have access to Thredd Portal.

Step 1: Obtain and install a Server Certificate

You first need to set up the Server certificate on your EHI server.

1. Obtain a Server Certificate from a Certificate Authority (CA) vendor of your choice, such as Verizon or Digicert or Amazon Web Services.

2. Install the Server certificate on your EHI listening endpoint.

3. Ensure that your Server presents this certificate to Thredd during the TLS handshake.

To understand how to do this in your specific case, refer to your Client library documentation.

Step 2: Log in to Thredd Portal and download the Authentication Certificate

Thredd provides an Authentication Certificate that you can use to validate EHI payload signatures. You download this certificate from the EHI Configuration page in Thredd Portal.

An Organisation Admin user must log in to Thredd Portal to download the certificate.

To download the Authentication Certificate:

1. Log in to Thredd Portal.

2. Navigate to the System Admin menu, select Organisation, and then select EHI Configuration.

3. The EHI Configuration page opens. Locate the Authentication Certificate panel and select Download Certificate.

The Authentication Certificate has a validity period, shown on the EHI Configuration page. Store the certificate securely, and make sure you download a replacement before it expires so that signature validation continues to work without interruption.

Step 3: Implement signature validation logic

To verify the authenticity and integrity of payloads, for example verifying that payload data has not been altered, you should implement logic to validate payload signatures. Signature validation is conducted at the application layer.

An overview of the logic is:

1. Locate and parse the signature — find the digital signature in the X-Thredd-Signature header.

2. Retrieve the public key — extract the public key from the Authentication Certificate that you downloaded from Thredd Portal.

3. Validate the signature — use the Public Key to cryptographically verify the digital signature against the EHI payload content.

   1. Successful validation: Guarantees the integrity and authenticity of the payload.

   2. Validation failure: Immediately rejects the notification and logs a critical security incident.

Step 4: Test your EHI endpoint for TLS communication

When you are ready, test the EHI endpoint with the online SSLLabs tool and OpenSSL. This is to ensure that you can successfully communicate with EHI over TLS.

When 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 for testing in the SSL Labs test screen test page. For example, api.thredd.com. The results appear similar to the following:

Figure: Passing Tests on SSL Labs

An "A" Grade results in the test passing. However, "B" does not result in a pass, and can indicate that the problem is due to a missing certificate on your Server.

Test using OpenSSL

You should run the following command that triggers the TLS handshake for the communication between Server (you) and the Client (Thredd). You receive a response for the Server certificate.

openssl s_client -connect ehi.yourdomain.com:443

Server Certificate result

The results for the Server certificate appear as follows:

Figure: Server Certificate Result Including Depth Settings

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

You might need to check the EHI listener endpoint configuration if the SSL Labs test does not give an "A" Grade response.

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/ehi/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>

Step 5: Inform Thredd that you are ready to use the EHI application

Once you have completed testing, provide the EHI endpoint to Thredd.

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

Thredd confirms to you when you are ready to continue to setting up your integration with EHI. See one of the following guides to learn more about EHI:

• EHI Guide (JSON version)

• EHI Guide (XML version)