Use IBM Cloud Hyper Protect Crypto Services to offload NGINX TLS

Transport Layer Security (TLS) encrypts communications between the client and the server to protect against potential hackers and man-in-the-middle attacks. TLS offloading is the process of using a Hardware Security Module (HSM) to perform the TLS encryption and decryption instead of the web server, this significantly reduces the risk of key compromise because the TLS encryption keys are located in the FIPS 140-2 Level 4 validated HSM. TLS is sometimes incorrectly referred to as SSL, which is a deprecated protocol that performed the same function as TLS.

TLS offloading relieves a web server of the processing burden of encrypting and decrypting traffic. Offloading TLS to a separate server helps with the following tasks:

  • inspecting client requests for dangerous content that could compromise the security of web servers
  • validating the identity of clients before any access is allowed to web resources
  • obfuscating URLs and fixing issues related to publishing applications with hard-coded elements
  • preventing the transfer of specific types of content based on patterns such as file extensions
  • redirecting traffic based on content type, such as sending all image requests to a server that’s optimized for serving images
  • caching web content on the load balancer, thus removing the need to re-request frequently accessed content from the web server
  • re-encrypting traffic going to the servers for additional security

For more background, see self-signed certificate, certificate signing request, and CA certificates.

Learning objectives

This tutorial explains how to use a Docker container (nginx-tls-offload) to perform TLS offloading on an NGINX web server using private keys protected by IBM Cloud Hyper Protect Crypto Service.

TLS Offload on NGINX with Hyper Protect Crypto Services

Estimated time

If all of the prerequisites are in place, it should take you no more than 60 minutes to complete this tutorial.


  1. Set up an IBM Cloud Pay-As-You-Go account, if you don’t have one already.
  2. Provision an instance of IBM Cloud Hyper Protect Crypto Service
  3. After the instance is provisioned, Copy information from the Overview tab for the following variables to be used later in this tutorial:
  4. Get setup with the Pre-requisites to initialize your HPCS instance.
  5. Perform the Key Ceremony by carefully following the procedure outlined in Initialize your HPCS instance.
  6. Create an API key to access your HPCS instance and Copy the API-Key for the following variable to be used later in this tutorial:
  7. Install curl and wget. If you are on an Ubuntu based Hyper Protect Virtual Server, use the following commands:
    • apt update && apt install -y curl
    • apt-get install wget


Here are the steps for completing this tutorial:

  1. Configuration
  2. Run your configuration
  3. Troubleshooting

Step 1. Configuration

  1. Logon to your Linux instance. You can provision an s390x based Hyper Protect Virtual Server for this tutorial.
  2. Create a working directory: ./nginx-tls-offload.
  3. Download the TAR file for your specific architecture:


    wget -O nginx-tlsoffload.tar.gz


    wget -O nginx-tlsoffload.tar.gz
  4. Untar the file:
    mkdir nginx-tls-offload
    tar -xvzf nginx-tlsoffload.tar.gz -C nginx-tls-offload --strip-components 1
  5. Build the Docker image:
    cd ./nginx-tls-offload
    docker build -t nginx-tls-offload:latest .

Step 2. Run your configuration

  1. Run the Docker container:
    docker run -d -p 2080:2080 -e LIBGREP11_CONNECTION_ADDRESS="<YOUR-HPCS-INSTANCE-EP11-ENDPOINT-URL>" -e LIBGREP11_CONNECTION_PORT="<YOUR-HPCS-INSTANCE-EP11-ENDPOINT-PORT>" -e LIBGREP11_IAMAUTH_INSTANCEID="<YOUR-HPCS-INSTANCE-ID>" -e LIBGREP11_IAMAUTH_APIKEY="<YOUR-IBMCLOUD-API-KEY>" -e LIBGREP11_CONNECTION_TLS_CACERT=/etc/ssl/certs/ca-certificates.crt -e LIBGREP11_IAMAUTH_TLS_CACERT=/etc/ssl/certs/ca-certificates.crt --name nginx-tlsoffload-container nginx-tls-offload:latest
  2. Test if the Docker container is performing TLS offloading as expected by using the following command:
    curl -k https://localhost:2080
    If the nginx-tls-offload container is working as expected, you should see the following response:
    Welcome to openssl engine & grep11 service!
    If you see this page, the openssl engine and grep11 service were successfully installed and working.

You have successfully offloaded your TLS workloads on an NGINX load balancer using keys managed by IBM Cloud Hyper Protect Crypto Services.

Step 3. Troubleshooting

If anything goes wrong, do the following:

  1. Stop the Docker container: docker rm -f nginx-tlsoffload-container
  2. Delete the Docker container: docker rmi nginx-tls-offload:latest
  3. Repeat Step 2 to rebuild the Docker image and run the Docker container.


Offloading TLS to a load balancer such as NGINX allows for a single, centralized point of control and management. Certificates and private keys only need to be managed in one place rather than on multiple servers. Policies can be applied and managed in one place. This greatly simplifies the administration overhead and also allows for separation of the security role from the application owner role.

You can try the technique described here with other load balancers, web application firewalls, caching servers, etc. You can also create machine learning algorithms that can benefit from inspecting the content that is dropped to create better algorithms that learn-as-you-go to ensure the safety of your web-applications environment.