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
docker-compose.yml file will also need a value set for
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
Next add a new section to
environment: that should be called
volumes:. In the
volumes:section add a line like this one:
This line for
volumes: will then define what value to set for the environment variable
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 email@example.com:~
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.
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
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 firstname.lastname@example.org:~
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
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.
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.