Use a Cloud HSM key to serve Apache traffic

This guide provides instructions for setting up an Apache server to use a Cloud HSM key for TLS signing on Debian 11 (Bullseye). You might need to modify these commands to work with your OS or Linux distribution.

You can find a Terraform-based blueprint version of this tutorial in the kms-solutions GitHub repository.

Before you begin

As a prerequisite, complete the configuration documented in OpenSSL Setup.

Once OpenSSL setup is complete, ensure that a recent version of Apache is installed:

sudo apt-get update
sudo apt-get install apache2

Configuration

Create a Cloud KMS-hosted signing key

Create a Cloud KMS EC-P256-SHA256 signing key in your Google Cloud project, in the key ring that you previously configured for OpenSSL:

gcloud kms keys create "KEY_NAME" --keyring "KEY_RING" \
  --project "PROJECT_ID" --location "LOCATION" \
  --purpose "asymmetric-signing" --default-algorithm "ec-sign-p256-sha256" \
  --protection-level "hsm"

Create a self-signed certificate with OpenSSL

Generate a self-signed certificate with the Cloud KMS-hosted signing key. You can use OpenSSL to use a PKCS #11 URI instead of a file path and identify the key by its label. In the Cloud KMS PKCS #11 library, the key label is the CryptoKey name.

openssl req -new -x509 -days 3650 -subj '/CN=CERTIFICATE_NAME/' \
  DIGEST_FLAG -engine pkcs11 -keyform engine \
  -key PKCS_KEY_TYPE=KEY_IDENTIFIER > PATH_TO_CERTIFICATE

Replace the following:

  • CERTIFICATE_NAME: a name for the certificate.
  • DIGEST_FLAG: the digest algorithm used by the asymmetric signing key. Use -sha256, -sha384, or -sha512 depending on the key.
  • PKCS_KEY_TYPE: the type of identifier used to identify the key. To use the latest key version, use pkcs11:object with the key's name. To use a specific key version, use pkcs11:id with the full resource ID of the key version.
  • KEY_IDENTIFIER: an identifier for the key. If you're using pkcs11:object, use the key's name—for example, KEY_NAME. If you're using pkcs11:id, use the full resource ID of the key or key version—for example, projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION.
  • PATH_TO_CERTIFICATE: the path where you want to save the certificate file.

If this command fails, PKCS11_MODULE_PATH might have been set incorrectly, or you might not have the right permissions to use the Cloud KMS signing key.

You should now have a certificate that looks like this:

-----BEGIN CERTIFICATE-----
...
...
...
-----END CERTIFICATE-----

Set up the Apache server

  1. Create a directory in /etc/apache2 to store your self-signed certificate in:

    sudo mkdir /etc/apache2/ssl
sudo mv ca.cert /etc/apache2/ssl

  2. Edit the 000-default.conf virtual host configuration files located in /etc/apache2/sites-available to provide the certificate file path and ensure that the SSLEngine is on.

    Here is a sample configuration listening on port 443:

      <VirtualHost *:443>
        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/html
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
        SSLEngine on
        SSLCertificateFile /etc/apache2/ssl/ca.cert
        SSLCertificateKeyFile "PKCS_KEY_TYPE=KEY_IDENTIFIER"
  </VirtualHost>

  3. Ensure Apache exports the environment variables correctly by adding them to the /etc/apache2/envvars file using your text editor of choice. You might need to edit the file as root using sudo. Add the following lines to the end of the file:

    export PKCS11_MODULE_PATH="<var>PATH_TO_LIBKMSP11</var>"
export KMS_PKCS11_CONFIG="<var>PATH_TO_PKCS11_CONFIG</var>"
export GRPC_ENABLE_FORK_SUPPORT=1

    Replace the following:

    • PATH_TO_LIBKMSP11: the path to libkmsp11.so.
    • PATH_TO_PKCS11_CONFIG: the path to pkcs11-config.yaml.

    GRPC_ENABLE_FORK_SUPPORT is needed for gRPC to include fork support and correctly run the Cloud KMS PKCS #11 library as part of the Apache server.

    If you want to authenticate using a service account key, you must also export a value for the GOOGLE_APPLICATION_CREDENTIALS environment variable.

Run your server

Enable the Apache SSL module, enable the virtualhost configuration, and add a test web page in your DocumentRoot folder:

sudo a2enmod ssl
sudo a2ensite 000-default.conf
echo '<!doctype html><html><body><h1>Hello World!</h1></body></html>' | \
  sudo tee /var/www/html/index.html

Restart your Apache server and test with curl that the configuration works as expected. The --insecure flag is needed to ignore self-signed certificate checks.

sudo systemctl restart apache2
curl -v --insecure https://127.0.0.1

If you encounter any errors, the Apache error log is a good starting place to see what went wrong. Authentication issues are a common source of errors. If you see PERMISSION_DENIED errors, make sure that you are fully authenticated and that the credentials file has the right permissions. To make sure you are fully authenticated, run the following command:

gcloud auth application-default login

To confirm that authentication was successful, the output should include the line Credentials saved to file: [/path/to/credentials.json].