Hardware Security Module#

This section describes the setup of a Hardware Security Module (HSM) in the Identity Server. Curity interfaces with an HSM using PKCS#11. This means that some kind of shared library is needed which provides this PKCS#11 capability. This is typically provided by the manufacturer of the HSM. Once an HSM is configured, keys can be used from the HSM. It is not required that all keys, public or private, reside on the HSM. It is possible to configure Curity to use some keys from its own configuration and others from the HSM. This can be especially helpful during testing, but can be useful even in production when it is desirable to configure the public keys in Curity rather than fetch them from the HSM (which may only be accessible over a network connection).

SSL, signature verification keys (public keys), signing keys, trust anchors, and client keys can all be configured to be stored on the HSM. When configuring a keystore, the admin just needs to specify that the key is located on the HSM. The admin node need not have access to the HSM; only run-time nodes that will use the keys housed in the HSM need access to the unit. This may be a subset of the run-time nodes depending on your deployment. There is currently no way to test the connectivity of the HSM from the admin node because it is assumed that this node won’t have access to an HSM.

In order for a key to be accessible to Curity, the HSM must contain not only a public key but also a certificate; without this, the key will not be found at run-time by Curity. The certificate can be self-signed, but it may also be signed by a trusted authority. The only algorithm supported at this time is RSA; elliptic curve and DSA keys cannot be used.

Entering a PIN#

In order for each Curity run-time node to access keys on an HSM, they will need to login. This is done using a PIN or pass phrase. There are four ways to provide this PIN to Curity:

  1. On the command line using the -i flag with the PIN as an argument (e.g., idsvr -i 11223344)
  2. On the command line using the -i flag with a file as an argument where that file contains the PIN (e.g., idsvr -i ~/.hsm-pin)
  3. On the command line using only the -i flag and entering the PIN when prompted
  4. Using the environment variable IDSVR_HSM_PIN.

If the -i flag is used with a PIN as an argument (as in the first or second option above), then the admin will not need to interactively provide one. When provided directly on the command line, the PIN will be included in the output of ps and other such tools; to avoid this, the second option of reading the PIN from a file can be used. With this option, the file can be a symlink or pipe as well. The third option of providing the PIN through an environment variable may also make it accessible to such tools. If the PIN is set interactively, it will only be resident in the node’s memory and not accessible from outside tools (like ps). This method requires interactive input from an admin on the console during startup, however.

Configuring the HSM#

Before any keystore can be configured as one residing in the HSM, the configuration for the unit must be defined. This is done by setting at least the path to the shared library that provides PKCS#11 support. This can be done using any of the management interfaces. For detailed information on the HSM-related settings, refer to the configuration reference .

Configuring the HSM in the GUI#

To configure an HSM using the admin UI, navigate to System → General. On this page, there is a section labeled Hardware Security Module. By default, this is toggled off.

Once it is toggled on, various settings can be configured. The two that are required are some sort of identifier or name and the path (as it will be on any run-time node that uses the HSM) to the shared library that provides the PKCS#11 implementation.

Either the slot list index or slot ID must be configured as well. By default, the list index is selected with a value of 0, but this can be changed as needed. The values will depend on the PKCS#11 provider used with the HSM. For example, to get this information with OpenSC, the pkcs11-tool command can be used as shown below:

$ pkcs11-tool -I
Cryptoki version 2.20
Manufacturer     OpenSC Project
Library          OpenSC smartcard framework (ver 0.17)
Using slot 0 with a present token (0x0)

To make the HSM as compatible with Curity as possible, the Include Compatibility Attributes option should be toggled on. If this poses a problem, select attributes can be enabled using the Mechanisms option. This option allows certain PKCS#11 mechanics to be enabled or disabled as needed. Valid mechanisms can be found in the PKCS#11 reference guide; any unrecognized value will cause the unit to be inaccessible and a warning to be logged.

Configuring the HSM in the CLI#

The CLI can also be used to configure the HSM. For example, enter configuration mode and set it as shown below:

admin@prod-curity1% set facilities crypto hardware-security-module library /usr/local/lib/opensc-pkcs11.so

To delete the HSM configuration, just issue the command delete facilities crypto hardware-security-module and commit the change.

Debugging the PKCS#11 Provider#

To get more information from the underlying PKCS#11 provider, you can pass the --debug-hsm flag to the idsvr command. This will cause all PKCS#11 keystore-related and provider-based messages to be written to the server log. You can also specify -Djava.security.debug=sunpkcs11,pkcs11keystore,pkcs11 in the JVM options of a certain node. If this method is used, the extra provider-related debugging information will be output after the node is restarted. When using this tactic, it can be helpful to include provider in the comma-separated list of debug message sources together with sunpkcs11, pkcs11keystore, and pkcs11. To set these and provider via the command-line, do not use the --debug-hsm parameter; instead, pass it via the JAVA_OPTS environment variable when starting the idsvr command (e.g., JAVA_OPTS=-Djava.security.debug=sunpkcs11,pkcs11keystore,pkcs11,provider idsvr).

Some HSM providers, like OpenSC, include a proxy library that logs all access to the PKCS#11 module. To use such an interceptor, configure the proxy library as the one that Curity should use. In the case of OpenSC, in particular, the library that is being proxied needs to be set via an environment variable. This can be done from the shell when starting the idsvr command (e.g., PKCS11SPY=/usr/local/lib/opensc-pkcs11.so idsvr). In the same way, other environment variables of OpenSC’s can be set before invoking idsvr; for instance, the environment variable, OPENSC_DEBUG, can be set to some debug level, like 9, which results in trace-level debug messages being printed to the server log.

Configure YubiHSM with IdentityServer#

For more information on how to configure YubiHSM check the link bellow

Was this helpful?