Apache#

You can configure Apache httpd to use NetHSM via the OpenSSL engine which then uses NetHSM’s PKCS#11 module.

The certificate file has to be on the disk but the private key can be used from the NetHSM.

A full example is available below.

OpenSSL Configuration#

Set up the OpenSSL engine by following the OpenSSL Engine setup guide. (OpenSSL Providers aren’t supported yet by Apache httpd.)

Httpd Configuration#

Add the following lines to your httpd.conf :

Listen 443
#...
LoadModule socache_shmcb_module modules/mod_socache_shmcb.so
LoadModule ssl_module modules/mod_ssl.so
#...

<VirtualHost *:443>
    DocumentRoot /usr/local/apache2/htdocs
    SSLEngine on
    SSLCertificateFile /certs/certificate.pem
    SSLCertificateKeyFile "pkcs11:object=webserver"
    ErrorLog /tmp/a-error.log
    CustomLog /tmp/a-access.log combined
</VirtualHost>

The SSLCertificateFile must point to a certificate file on the disk.

The SSLCertificateKeyFile should be a PKCS#11 URI pointing to the private key in the NetHSM.

Note

You must generate the certificate separately and then upload it to the NetHSM. If the certificate on disk and the key in the NetHSM don’t match httpd won’t start.

libnethsm_pkcs11 Configuration#

slots:
  - label: LocalHSM
    description: Local HSM (docker)
    url: "https://192.168.3.161:8443/api/v1"
    operator:
      username: "operator"
      password: "opPassphrase"

To secure the password you can provide it via an environment variable (see Setup) or provide it in the httpd configuration:

SSLCertificateKeyFile "pkcs11:object=webserver;type=private;pin=opPassphrase";

Example#

If you want to experiment with the given example use git to clone the nethsm-pkcs11 repository and run the following commands:

Warning

Running the generate script deletes the webserver key and replaces it.

  1. Configure a NetHSM, either a real one or a container. See the getting-started guide for more information.

  2. If your NetHSM is not running on localhost, you will need to change the URL of the curl requests in container/apache/generate.sh to point to your NetHSM.

  3. Change the libnethsm_pkcs11 configuration to match your NetHSM in container/apache/p11nethsm.conf.

  4. Generate the certificate and key.

./container/apache/generate.sh

  1. Build the container.

docker build -f container/apache/Dockerfile . -t pkcs-httpd

  1. Run the container.

docker run -p 9443:443 -p 9080:80 pkcs-httpd

The container will be available at https://localhost:9443/.