Using Signing Service With HSM and PKCS11

Signing Service can optionally store certificates in an HSM (Hardware Security Module) instead of in the local database. This can provide an additional layer of security and management for the certificate content. This option requires setting up an account with a third-party HSM provider. The following instructions will provide an example for how to set this up with Google as the HSM provider. 

Credentials: Once an account is set up for Google HSM, first download the JSON file provided by Google that contains credentials to authenticate as a service account. Keep this JSON file for later use when installing Signing Service. More information on this is available from Google.

Project: Signing Service will need to know the following values for the Google HSM account: project ID, location ID, and key ring name. Locate these values or speak with your Google administrator to obtain them. 

Setup (Docker): After completing the basic setup to install Signing Service to a Docker container, find the docker-compose.yml file and find the section for app > environment. Find the section for the following environment variables and enter the values obtained from Google earlier: HSM_PROJECT_ID HSM_LOCATION_ID HSM_KEY_RING_NAME

The docker-compose.yml file will also need a value set for KEY_WRAP_URL. Set KEY_WRAP_URL to be the download link for Key Wrap.

Next set a value for GOOGLE_APPLICATION_CREDENTIALS. This value should be the complete file path for where the HSM JSON credentials file will be stored on the Docker app container. 

Next add a new section to docker-compose.yml above environment: that should be called volumes:. In the volumes:section add a line like this one: 

/path/on/host/to/hsm_credentials_folder:/path/on/docker/app/container/to/create/for/hsm_credentials_folder

This line for volumes: will then define what value to set for the environment variable GOOGLE_APPLICATION_CREDENTIALS.

Save these changes to the docker-compose.yml file and then run the docker-deploy.sh script that was run when first installing Signing Service. 

Setup (AWS): After completing the basic setup to install Signing Service to an AWS Elastic Beanstalk environment, use the eb setenv command in Terminal to set the following environment variables using the values obtained from Google earlier: HSM_PROJECT_ID HSM_LOCATION_ID HSM_KEY_RING_NAME

Next it will be necessary to copy the Google HSM credentials JSON file to the EB environment. Get a copy of this JSON file and note it’s local location path. Then run the eb ssh command in Terminal and note the values shown in output for connecting the the EB environment. Disconnect from the environment and then use scp to copy the file to the EB environment using the following example: 

scp -i /path/to/local/.ssh/aws-eb-key /path/to/local/signing-service-config.json ec2-user@aws.eb.ip.address:~

If desired the JSON file can be moved to another location on the EB environment. Once the JSON file is copied to the EB environment, use the eb setenv in Terminal to set an environment variable called GOOGLE_APPLICATION_CREDENTIALS to the full path to the JSON file on the EB environment. 

Key Wrap Import

Once these setup steps are completed, reload the Signing Certificates page in Signing Service. Next to the Import signing certificate button will be a new button called Key Wrap import. Click the new button to go to the page for Key Wrap and follow the instructions to install and use Key Wrap. 

Key Wrap is an application that allows for securely wrapping a certificate from macOS Keychain. Once wrapped the certificate will remain secure while it is imported to the HSM. Signing Service will then be able to access these imported certificates from the HSM and can make them available for signing just like any certificates that were imported locally. 

When the HSM option is enabled in Signing Service, the Signing Certificates page will have a status indicator for each certificate to show if it is stored locally or in the HSM. Signing requests for HSM certificates will then use the HSM to performing the signing operation and Signing Service will deliver the signature result in the same manner used for local certificate signing requests. All other aspects of using an HSM certificate will be the same as for local certificates.

PKCS11

Signing Service also supports importing certificates to an HSM and signing using PKCS11. The following demonstrates how Signing Service can be configured to use Google HSM with PKCS11. 

Signing Service will need a PKCS11 library file for the specific HSM. For Google this file is available from their GoogleCloudPlatform Github repo. The PKCS11 library file required will have the extension .so. 

Signing Service may also need a PKCS11 configuration YAML file. For Google HSM this file requires content like the following example: 

tokens: - key_ring: "projects/project-name/locations/us/keyRings/key-ring-name"

This YAML file configures the key ring that will be used on Google HSM. 

After getting the PKCS11 library file and the YAML configuration file, copy these to a local folder called signing-service-config. Also add the Google HSM JSON file to this folder as well. 

Next copy the local signing-service-config folder to the app environment. This can be done for AWS EB using the scp command in Terminal using the following example: 

scp -r -i /path/to/local/.ssh/aws-eb-key /path/to/local/signing-service-config-folder ec2-user@aws.eb.ip.address:~

Next set the following environment variables. For AWS EB this can be done by using the eb setenv command.KMS_PKCS11_LIB KMS_PKCS11_CONFIG GOOGLE_APPLICATION_CREDENTIALS

KMS_PKCS11_CONFIG should be set to the EB environment file path to the PKCS11 library .so file.  KMS_PKCS11_CONFIGshould be set to the EB environment file path to the PKCS11 configuration YAML file. For Google HSM there should also be an environment variable for GOOGLE_APPLICATION_CREDENTIALS set to the HSM configuration JSON file. 

PKCS11 Import

Once these files are copied to the EB environment and the environment variables are set, go to the Signing Certificates page in a browser and click the Import signing certificate button. Find the form field for Certificate and enter a PEM format file with the file extension .cer. This file should represent a certificate that is currently available in the HSM with a known certificate ID. Current certificate IDs in the HSM will be shown. Enter or click on the corresponding certificate ID, then click Import. Once added to Signing Service, a PKCS11 certificate will be available for signing and authorizing for use by registered Signing Manager client machines.