Table of Contents

Hardware Security Modules (HSM) Keystores

Note

PhenixID server has the ability to use keystores stored in a HSM. This article describes how to configure PhenixID server to use HSM keys.

Overview

Keys stored in a Hardware Security Module can be used for all server-side signing operations. This includes:

  • Signing SAML Assertions and SAML Responses
  • Signing client certificates for OneTouch
  • Signing PDF-files

Please make sure to have a backup copy of the configuration before adding the new settings.

Prerequisites

  • Installation and configuration of the HSM. This is out-of-scope for this document. Consult your HSM supplier documentation. The HSM must have a PKCS11 interface.
  • Keys imported into HSM.
  • Alias of key to use must be known.
  • Path to the HSM Provider config file must be known.
  • HSM Password must be known.

Configuring module

  1. Open the Advaced tab in Configuration Manager.
  2. Open Modules nodes. Locate the crypto module. If not present, create. If created make sure to update the appropriate node "module_refs" property with the module id. Add the following parameters:
    • crypto_mode - set to "hsm"
    • hsmprovider - path of the HSM configuration file
    • hsm_password - the HSM's password
{
  "module": "com.phenixidentity~phenix-crypto",
  "enabled": "true",
  "config": {
  "crypto_mode": "hsm",  //This must be set to "hsm" Note that this is not the path to the provider file it self. It is the path to the configuration file.
  "hsmprovider": "", //The file path to the hsm conf file. 
  "hsm_password": "my super secret passwors"  //The hsm password
}

The hsm conf file must contain properties name, library and slot. The conf file might include additional properties. Please consult your hsm documentation for appropriate values.

Example:

"hsmprovider": "/opt/phenixid/server/config/hsm.conf"

hsm.conf content:

name=SoftHSM
library=/opt/Cellar/softhsm/2.0.0/lib/softhsm/libsofthsm2.so
slot=0

Note that switching to HSM after using internal certificates will require reconfiguration.

Using key from HSM

  1. Open the Configuration tab in Configuration Manager.
  2. Locate Keystores.
  3. Open Keystores. Configure key to use by simply adding:
    {
        "id": "bhull",
        "certificateAlias": "bhull"
    }

Example of total Keystores configuration:

[    
    {
        "id": "bhull",
        "certificateAlias": "bhull"
    },
    {
        "id": "samlsigner",
        "certificateAlias": "samlsigner"
    }
]

See the reference documentation on Java PKCS#11: PKCS#11 Reference Guide

Referrals to Keystore object

Make sure your configuration points to the newly created keystore. This is an example of a SAML Identity Provider object:

    {
        "id": "87697ae0-bbf4-402d-8e4f-fcf60d43717a",
        "name": "SAML IDP",
        "keystore": "myHsmKey",
        "entityID": "https://myserver.phenixid.se/saml/idp/authn1",
        "requireSigned": "true",
        "postSSOURL": "https://myserver.phenixid.se/saml/authenticate/authn1",
        "created": "2017-04-06T06:35:35.955Z"
    }
Cryptography