Use keystores in Hardware Security Module (HSM)

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

Prerequisites

- Installation and configuration of the HSM. This is out-of-scope for this document. Consult your HSM supplier documentation.

- Keys imported into HSM

- Alias of key to use must be known

Configuring module

Open the Advaced tab in Configuration Manager.

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.

{
"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 re configuration.

Using key from hsm

Open the Configuration tab in Configuration Manager.

Locate Keystores.

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 ORACLE ref doc on Java PKCS#11:

https://docs.oracle.com/javase/8/docs/technotes/guides/security/p11guide.html