HSMs and ForgeRock software

This page covers how you can use a Hardware Security Module (HSM) to protect ForgeRock software private and secret keys.

On protecting secrets

You must protect private keys and secret keys that servers use for cryptographic operations:

Operating system protections: In many deployments, operating system protections are sufficient. Operating systems are always sufficient for public keys and keystores that do not require protection.

Isolate the server account on the operating system where it runs, and allow only that account to access the keys. If you store the keys with version control software, also control access to that.

This deployment option generally offers a better performance/cost ratio. You must take more care to prevent private and secret keys from being exposed, however.
HSM: For stronger protection, you can use an HSM.

An HSM is a secure device that holds the keys, and protects them from unauthorized access. With an HSM, no one gets direct access to the keys. If an attacker does manage to break into an HSM and theoretically get access to the keys, HSM are designed to make the tampering evident, so you can take action.

To put a private or secret key on an HSM, you have the HSM generate the key. The key never leaves the HSM. Instead, if you need the result of a cryptographic operation involving the key, you authenticate to the HSM and request the operation. The HSM performs the operation without ever exposing any private or secret keys. It only returns the result.

An HSM can be certified to comply with international standards, including FIPS-140 and Common Criteria. An HSM that is certified to comply with these standards can be part of your supported ForgeRock software solution.

ForgeRock software uses the HSM through standard PKCS#11 interfaces, and supports the use of compliant cryptographic algorithms.

An HSM generally offers higher security, but with a significant cost and impact on performance. Good HSMs and standards compliance come with their own monetary costs.

In terms of performance, each cryptographic operation incurs at minimum a round trip on a secure connection, compared with an operation in local memory for keys on the system. Even if the deployment may guarantee the same throughput, take the latency into account when deciding to deploy with HSMs.
Key management services: Key management services, such as Google Cloud KMS and others, offer similar advantages and tradeoffs as HSMs.

Latency for online key management services can be very high.

Performance

Throughput, the rate of operations completed, might or might not be impacted by your choice of protecting secrets.

Latency, how long individual operations take, will be impacted by your choice of protecting secrets.

Performance Example

For example, suppose you want a system that signs one million JWTs per second. As long as you can distribute the signing key across enough hardware, your system can sign one million JWTs a second. This is true even if each signing operation takes ten seconds. You simply need ten million systems, and the network hardware to use them in parallel. Throughput therefore depends mainly on how much you can spend.

Suppose, however, that each signing operation must take no longer than ten milliseconds. Furthermore, suppose you have an HSM that can perform a signing operation in one millisecond, but that the network round trip from the system to the HSM takes an average of eleven milliseconds. In this case, you cannot fix performance by buying a faster HSM, or by somehow speeding up the software. You must first reduce the network time if you want to meet your latency requirements.

Perhaps the same signing operation with a key stored on the operating system takes two milliseconds. Consider the options based on your cost and security requirements.

Performance also depends on the following:

The impact of latency is greater when performing symmetric cryptographic operations (AES, HMAC) compared to public key cryptography (RSA, EC).
For public key cryptography, only operations that use the private key must contact the HSM (signing, decryption).

Operations using the public key (verifying a signature, encryption) retrieve the public key from the HSM once, and then use it locally.
Most public key cryptography uses hybrid encryption, where only a small operation must be done on the HSM, and the rest can be done locally.

For example, when decrypting a large message, typically, the HSM is only used to decrypt a per-message AES key that is then used to decrypt the rest of the message locally.

Similarly, for signing, the message to sign is first hashed in-memory using a secure hash algorithm, and only the short hash value is sent to the HSM to be signed.

In contrast, when using symmetric key algorithms directly with an HSM, the entire message must be streamed to and from the HSM.

How ForgeRock services interact with HSMs

ForgeRock services built with Java interact with HSMs through Java PKCS#11 providers.

The PKCS#11 standard defines a cryptographic token interface, a platform-independent API for accessing an HSM, for example. ForgeRock services support the use of the Sun PKCS11 provider.

The Sun PKCS11 provider does not implement every operation and algorithm supported by every HSM. For details on the Sun PKCS11 provider’s capabilities, refer to the JDK Providers Documentation, and the JDK PKCS#11 Reference Guide.

How you configure the JVM to use your HSM depends on the Java environment and on your HSM. ForgeRock services do not implement or manage this configuration, but they do depend on it. Before configuring ForgeRock services to use your HSM, you must therefore configure the JVM’s Sun PKCS11 provider to access your HSM. For details on how to configure the Java Sun PKCS11 provider with your HSM, refer to the documentation for your HSM, and the JDK PKCS#11 Reference Guide.

Sun PKCS11 provider hints

The provider configuration depends on your provider.

Compare the following hints for ForgeRock software with the documentation for your HSM:

name = FooHsm: The name used to produce the Sun PKCS11 provider instance name for your HSM.

FooHsm is just an example.
CKA_TOKEN = false: Keys generated using the Java keytool command effectively have this set to true. They are permanent keys, to be shared across the deployment.

Set this to false to prevent temporary keys for RSA hybrid encryption used by some platform components from exhausting HSM storage.
CKA_PRIVATE = true: The key can only be accessed after authenticating to the HSM.
CKA_EXTRACTABLE = false
CKA_SENSITIVE = true: CKA_EXTRACTABLE = false means the key cannot be extracted unless it is encrypted.

CKA_SENSITIVE = true means do not let the secret key be extracted out of the HSM. Set this to true for long-term keys.

Only change these settings to back up keys to a different HSM, when you cannot use a proprietary solution. For example, you might change these settings if the HSMs are from different vendors.
CKA_ENCRYPT = true: The key can be used to encrypt data.
CKA_DECRYPT = true: The key can be used to decrypt data.
CKA_SIGN = true: The key can be used to sign data.
CKA_VERIFY = true: The key can be used to verify signatures.
CKA_WRAP = true: The key can be used to wrap another key.
CKA_UNWRAP = true: The key can be used to unwrap another key.

When using keytool

When using the Java keytool command to generate or access keys on the HSM, set the following options appropriately:

-alias alias: If key pair generation fails, use a new alias for the next try. This prevents the conflicts where the previous attempt to create a key was only a partial failure, leaving part of key pair using the previous alias.
-keystore none: Required setting.
-providername providerName: Required setting.

Prefix SunPKCS11- to the name in the configuration. If, in the Sun PKCS11 configuration, name = FooHSM, then the providerName is SunPKCS11-FooHSM.
-storetype pkcs11: Required setting.

If necessary, add the following settings:

-providerClass sun.security.pkcs11.SunPKCS11: Use this to install the provider dynamically.
-providerArg /path/to/config/file.conf: Use this to install the provider dynamically.

The exact configuration depends on your HSM.

When Java cannot find keys

When keys generated with one Java PKCS#11 provider are later accessed using the Sun PKCS11 provider, the providers may have different naming conventions.

Java’s KeyStore abstraction requires that all private key objects have a corresponding Certificate object. SecretKey objects, such as AES or HMAC keys, are excluded from this requirement.

The Sun PKCS11 KeyStore provider loops through all defined private key entries in the HSM (class = private key), and tries to match them up with a corresponding certificate entry (class = certificate) by comparing the CKA_ID of the certificate entry to the CKA_ID of the private key entry. There may be multiple certificates using the same private key pair The matching process can take several seconds at startup time if you have many keys.

If keys are not found, it is likely that the private key entry CKA_ID does not match the certificate entry CKA_ID.

HSM features and ForgeRock services

This part outlines how some ForgeRock platform features support HSMs.

JWT encryption algorithms

JWT Encryption Algorithm	Java Algorithm Equivalent	Supported by Sun PKCS11 Provider?
RSA1_5	RSA/ECB/PKCS1Padding⁽¹⁾	Yes
RSA-OAEP	RSA/ECB/OAEPWithSHA-1AndMGF1Padding	No
RSA-OAEP-256	RSA/ECB/OAEPWithSHA-256AndMGF1Padding	No
ECDH-ES (+A128KW, and so on)⁽²⁾	ECDH (KeyAgreement vs. Cipher)	Yes
dir with A128GCM, A192GCM, A256GCM	AES/GCM/NoPadding	Yes
dir with A128CBC-HS256, and so on	AES/CBC/PKCS5Padding + HmacSHA256, and so on	No
A128KW, A192KW, A256KW	AESWrap	No

JWT Encryption Algorithm

Java Algorithm Equivalent

Supported by Sun PKCS11 Provider?

RSA1_5

RSA/ECB/PKCS1Padding⁽¹⁾

Yes

RSA-OAEP

RSA/ECB/OAEPWithSHA-1AndMGF1Padding

RSA-OAEP-256

RSA/ECB/OAEPWithSHA-256AndMGF1Padding

ECDH-ES (+A128KW, and so on)⁽²⁾

ECDH (KeyAgreement vs. Cipher)

Yes

dir with A128GCM, A192GCM, A256GCM

AES/GCM/NoPadding

Yes

dir with A128CBC-HS256, and so on

AES/CBC/PKCS5Padding + HmacSHA256, and so on

A128KW, A192KW, A256KW

AESWrap

⁽¹⁾ PKCS#1 version 1.5 padding has known vulnerabilities and should be avoided.

⁽²⁾ The Sun PKCS11 implementation of ECDH KeyAgreement requires that the derived key be extractable. This is not a security issue, as the derived key is unique to each message, and therefore no more sensitive than the message it is protecting, due to the use of fresh ephemeral keys for each message (ECIES). To ensure that the derived keys are extractable, add the following to the PKCS11 configuration file:

attributes(*,CKO_PRIVATE_KEY,CKK_EC) = {
  CKA_SIGN = true
  CKA_DERIVE = true
  CKA_TOKEN = true
}

attributes(generate,CKO_SECRET_KEY,CKK_GENERIC_SECRET) = {
  CKA_SENSITIVE = false
  CKA_EXTRACTABLE = true
  CKA_TOKEN = false
}

This also ensures that EC keys generated with the keytool command are marked as allowing ECDH key derivation. The derived keys are also marked as CKA_TOKEN = false, which ensures that the derived keys are only created as session keys, and automatically deleted when the session ends to prevent filling up the HSM with temporary keys.

JWT signing algorithms

JWT Signing Algorithm	Java Algorithm Equivalent	Supported by Sun PKCS11 Provider?
HS256, HS384, HS512	HmacSHA256, HmacSHA384, HmacSHA512	Yes
RS256, RS384, RS512	SHA256WithRSA, SHA384WithRSA, SHA512WithRSA	Yes
PS256, PS384, PS512	RSASSA-PSS or SHA256WithRSAAndMGF1, and so on	No
ES256, ES384, ES512	SHA256WithECDSA, and so on	Yes
EdDSA	Under development	No

JWT Signing Algorithm

Java Algorithm Equivalent

Supported by Sun PKCS11 Provider?

HS256, HS384, HS512

HmacSHA256, HmacSHA384, HmacSHA512

Yes

RS256, RS384, RS512

SHA256WithRSA, SHA384WithRSA, SHA512WithRSA

Yes

PS256, PS384, PS512

RSASSA-PSS or SHA256WithRSAAndMGF1, and so on

ES256, ES384, ES512

SHA256WithECDSA, and so on

Yes

EdDSA

Under development

Configure ForgeRock services to use an HSM

Once you have configured the Java environment to use your HSM through the Sun PKCS11 Provider, you can configure ForgeRock software to use the HSM:

AM: Refer to Configuring secrets, certificates, and keys.
DS: Refer to PKCS#11 hardware security module.
IDM: Refer to Configuring IDM for a hardware security module (HSM) device.
IG: Refer to Secrets, and HsmSecretStore.

ForgeRock Identity Platform 7.3