Add configuration for keys stored in HSM

This document is written for PhenixID Server.

The reader should have some basic knowledge about PhenixID Server.

This document describes how to configure the system to read keys stored in a Hardware Security Module (HSM).

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

- HSM installed. HSM must have a pkcs11 interface

- Keys stored in HSM. Alias of keystore to use must be known.

- Path to the HSM Provider config file must be known.

- HSM Password must be known.

Change crypto module mode

Log in to the configuration UI, go to the "Advanced" tab and press the pencil to the right of "Modules".

Find the crypto module. Add the config parameters crypto_mode, hsmprovider and hsm_password. Change hsmprovider and hsm_password to suite your environment.

	{
		"name": "com.phenixidentity~phenix-crypto",
		"singleton": "true",
		"config": {
        "crypto_mode" : "hsm",
        "hsmprovider" : "/opt/hsm/softhsm.conf",
        "hsm_password" : "xxxx"
      },
		"enabled": "true",
		"created": "2017-04-05T14:19:26.709Z",
		"id": "27b26f37-a139-46d9-a770-cdbe04d4bb17"
	}

When done press Stage changes/Commit changes.

hsmprovider

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/hsm/hsm.conf"

hsm.conf content:

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

Referring to key store in HSM

Log in to the configuration UI, go to the "Advanced" tab and press the pencil to the right of "Keystores".

Add a new keystore object that points to the HSM key. 

{
		"id": "myHsmKey",
		"certificateAlias": "0"
	}

When done press Stage changes/Commit changes.

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"
	}