IBM Developer

Tutorial

Offload Transport Layer Security using a hardware security module

Use Apache HTTPD and Red Hat Enterprise Linux for TLS offloading on IBM LinuxONE

By Sandeep Batta, Timo Kussmaul, Robbie Avill

On this page

Transport Layer Security (TLS) encrypts communications between the client and the web server to protect against potential hackers and man-in-the-middle attacks. While encryption protects data, it introduces latency because of the additional processing the webserver must do to unencrypt data before it can be processed.

"TLS offloading" is the process of using a hardware security module (HSM) to redirect encrypted traffic away from the web server to alleviate its processing load. This process "offloads" the TLS encryption and decryption to the HSM, instead of trusting the web server to do so, which significantly reduces the risk of key compromise. It also helps with the following tasks:

  • Generating the SSL key pair on an HSM or cryptographic service
  • Storing the SSL private key on an HSM or cryptographic service
  • Performing the crytpographic operations for SSL on an HSM or cryptographic service

For more background, see self-signed certificate, certificate signing request (CSR), and certificate authority.

Learning objectives

By completing this tutorial, you'll learn how to use Apache HTTPD on Red Hat Enterprise Linux (RHEL) 8.10 to perform TLS offloading using private encryption keys that are protected by an on-premise FIPS 140-2 Level 4 HSM IBM LinuxONE server. The setup will look something like this:

tlsoffload-with-httpd

Estimated time

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

Prerequisites

  • Access to a RHEL 8.10 server
  • Access to on-premise HSM / GREP11 Services on LinuxONE; you will need the following information:
    • IP address to access the GREP11 server
    • Port number to access the GREP11 server
    • Certificates to access the GREP11 server, specifically:
      • GREP11 CA Certificate
      • Client Certificate
      • Client Key
  • Access to a certificate authority (CA) to create a certificate from a certificate signing request (CSR) that is being generated using a private-key from the HSM.

Step 1. Prepare the server

  1. Log on to your RHEL 8.10 server.

  2. Create the required directory structure:

    mkdir -p /etc/ep11client/certs
mkdir -p /etc/pki/tls/certs

  3. Install packages:

    yum install -y wget "libp11*" "httpd*" mod_ssl gnutls-utils

Step 2. Configure GREP11-HSM access

  1. Download the pkcs11-grep11 library:

    cd /etc/ep11client
wget https://github.com/IBM-Cloud/hpcs-pkcs11/releases/download/v2.6.8/pkcs11-grep11-s390x.so.2.6.8
ln -s pkcs11-grep11-s390x.so.2.6.8 pkcs11-grep11.so

  2. Copy the certificates for GREP11-HSM to /etc/ep11client/certs. You should have the following files:

    • /etc/ep11client/certs/client.key: The private client key to access the server.
    • /etc/ep11client/certs/client.pem: The client certificate to access the server.
    • /etc/ep11client/certs/grep11-ca.pem The GREP11 root CA certificate.
  3. Copy sample-grep11client.yaml to /etc/ep11client/grep11client.yaml.

  4. Update the following attributes in the /etc/ep11client/grep11.client.yaml file.

    • <GREP11-ENDPOINT-IP>: The IP address to access the GREP11 server.
    • <GREP11-ENDPOINT-PORT>: The port number to access the GREP11 server.
    export uuid1=$(uuidgen)
export uuid2=$(uuidgen)
sed -i -e "s/<UUID-#1>/$uuid1/g" /etc/ep11client/grep11client.yaml
sed -i -e "s/<UUID-#2>/$uuid2/g" /etc/ep11client/grep11client.yaml

  5. Identify the PKCS11-GREP11 module to the host server:

    echo "module: /etc/ep11client/pkcs11-grep11.so" > /etc/pkcs11/modules/pkcs11-grep11.module

  6. Create a Keystore in the GREP11 server, with the init-token command:

    p11tool --initialize "pkcs11:model=GREP11;manufacturer=IBM" --label grep11

Step 3. Configure OpenSSL

  1. Add the following lines to the file /etc/pki/tls/openssl.cnf, just before the [ default_modules ] section:

    engines = engine_section

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib64/engines-1.1/libpkcs11.so
MODULE_PATH = /etc/ep11client/pkcs11-grep11.so
PIN = 12345678
init = 0

  2. Check whether openssl is setup correctly:

    openssl version -a
openssl engine -t pkcs11

Step 4. Create an SSL private key and certificates with HSM

  1. Create a private key in the HSM with the label httpdsslkey:

    p11tool --provider /etc/ep11client/pkcs11-grep11.so --login --generate-rsa --bits 2048 --label "httpdsslkey" --outfile httpdsslkey.pub "pkcs11:model=GREP11;manufacturer=IBM"

  2. Construct the URL for the private key in HSM:

    p11tool --provider=/etc/ep11client/pkcs11-grep11.so --list-all 1>/tmp/p11tool-output
export URL=$(cat /tmp/p11tool-output | grep -e "URL" | grep -e "object=httpdsslkey" | awk -F 'URL: ' '{print $2}' | sed 's/public/private/')

  3. Construct the key to be used for HSM calls:

    export key=$URL";pin-value=12345678"

  4. Create a certificate signing request (CSR) with a private key in the HSM:

    cd /etc/pki/tls/certs
openssl req -engine pkcs11 -keyform engine -key $key -subj "/C=US/ST=New York/L=Armonk/O=IBM/OU=CIO/CN=www.example.com" -new -out www.example.com-csr

  5. Use the file www.example.com-csr to generate a certificate chain. You should get the following files back from the CA:

    • Leaf Certificate
    • Intermediate Certificate
    • Root Certificate
  6. Concatenate the Leaf and Intermediate certificates, one after the other, in the file /etc/pki/tls/certs/www.example.com-bundle.crt.

  7. You should now have the following files in /etc/pki/tls/certs:

    www.example.com-bundle.crt
www.example.com-csr

Step 5. Configure HTTPD

  1. Edit and adapt the file /etc/httpd/conf.d/ssl.conf:

    • Enable SSL:

         SSLEngine on

    • Define the SSL certificate file:

         SSLCertificateFile /etc/pki/tls/certs/www.example.com-bundle.crt

    • Define the SSL certificate key file. Note: The following line is an example. You will need to add your key URL:

      SSLCertificateKeyFile "pkcs11:model=GREP11;manufacturer=IBM;serial=000%2F0000;token=test;id=%1A%E3%C9%29%64%96%50%5E%BD%45%89%B2%5F%21%52%F3%1B%C3%0D%13;object=httpdrsa1;type=private;pin-value=12345678"

  2. Copy sample-ssl-index.html to /var/www/html/index.html:

  3. Restart Apache HTTPD:

    httpd -X

    Note: The -X flag is a temporary measure to run HTTPD in single-threading mode, without forking.

Step 6. Test the TLS offload

  1. Map the host name www.example.com to the IP-address of your server by editing your local (client) hosts-file.

  2. Open a browser and go to https://www.example.com:443. If everything is working as expected, you will see a page with the following message:

    Welcome to TLS Offload with HTTPD, OpenSSL & GREP11 service on a LinuxONE HSM!

Summary and next steps

Offloading Transport Layer Security with a hardware security module allows for a single, centralized point of control and management of private keys used to create certificates. If HSM services are part of a larger encryption services platform, policies can be created to align with an organization's security policies. This greatly simplifies the administration overhead and enables the separation of the security role from the application owner role by the security administrator.

The procedure described here is applicable, with some modifications, to other load balancers, web application firewalls, and caching servers.

You should now understand how to offload transport layer security using a hardware security module. For additional information, check out the following resources: