Entrust HSM Integration

Entrust HSM integrates with Akana's external keystore feature to securely store and manage cryptographic keys outside the Akana database.

On this page:

Prerequisites

Before you integrate Entrust HSM with Akana, complete the following prerequisites:

  • Install and configure Entrust HSM: Complete the installation and configuration according to the Entrust documentation for your HSM device. For information about installing and configuring a specific Entrust HSM device, refer to the product documentation for the device.
  • Verify connectivity and keystore access: Confirm that each Akana container host(s) can connect to the Entrust HSM or access the Remote File System (RFS) used by nShield. To verify connectivity to the HSM, run the /opt/nfast/bin/enquiry command and review the output to confirm that the HSM is reachable.
  • Akana integration requirements: Obtain or record the following values for your Entrust nShield or nCipher HSM deployment:
    NameDescription
    Provider namenCipherKM
    Fully qualified provider classcom.ncipher.provider.km.nCipherKM
    Keystore typenCipher.sworld
    Provider JAR locationnCipherKM.jar location, typically /opt/nfast/java/classes.
    Keystore locationDevice-specific path to the Security World or keystore file, typically /opt/nfast/kmdata/local.
    Keystore passwordOCS or module passphrase configured on the Entrust device. A password might not be required for some devices.
  • Generate or import PKI keys: Create or import PKI keys in the Entrust HSM keystore for each identity that requires a key. If Policy Manager and Community Manager (PM/CM) use a different keystore from Network Director (ND), create or import each key in the keystore used by the corresponding component.

    Ensure the keystore file exists first by importing an existing key if necessary. The following example uses an external Oracle JRE to generate a 2048-bit RSA key pair for the pmcm identity. Depending on your security requirements, use a key size of 2048 or 4096 bits.

    {JAVA_HOME}/java -Dprotect=module -DignorePassphrase=true sun.security.tools.keytool.Main -genkeypair -alias pmcm -keyalg rsa -keysize 2048 -sigalg sha512withrsa -validity 360 -storetype nCipher.sworld -keystore /home/keystorend.dat -dname "CN=pmcm, OU=AKANA, O=PERFORCE, L=PARKER, ST=CO, C=US"

    Create or import keys for the following identities, as applicable:

    • pmadmin: Policy Manager engine identity.
    • Containers, listeners, and outbound identities: Required by your security configuration.
    • (Optional) User identities referenced in JOSE Security Policy v2 and JOSE Profile-Driven Security Policy configurations.
    • (Optional) Services that use Server Name Indication (SNI) to serve a service certificate over a TLS connection.
    • (Optional) User identities referenced by the Akana OAuth/OIDC provider or an External OAuth provider.
    • (Optional) The key used for SAML Web SSO.

Java Virtual Machine (JVM)/Java Cryptography Extension (JCE) provider setup provider setup

Complete the following steps to register the Entrust provider with the Java runtime used by each Akana Platform container:

  1. Open the java.security provider file at $JAVA_HOME/conf/security/java.security to add and register the Entrust security provider. You can register providers by using abbreviated names. For example, you can use security.provider.1=SUN instead of sun.security.provider.Sun. The existing provider list might use abbreviated provider names, as shown in the following example: 
    security.provider.1=SUN
security.provider.2=SunRsaSign
security.provider.3=SunEC
security.provider.4=SunJSSE
security.provider.5=SunJCE
security.provider.6=SunJGSS
security.provider.7=SunSASL
security.provider.8=XMLDSig
security.provider.9=SunPCSC
security.provider.10=JdkLDAP
security.provider.11=JdkSASL
security.provider.12=SunPKCS11
security.provider.13=nCipherKM
security.provider.14=BouncyCastleProvider
  2. In the java.security file, add or update the jdk.security.provider.preferred property so that the Entrust provider (nCipherKM) is preferred for RSASSA-PSS and HMAC signatures, as shown below: 
    jdk.security.provider.preferred=Signature.RSASSA-PSS:nCipherKM, \
                                                Signature.HS256:nCipherKM, \
                                                Signature.HS384:nCipherKM, \
                                                Signature.HS512:nCipherKM
  3. (Optional) If you cannot modify the default java.security file, create a custom java.security file that specifies your preferred provider order and then add the following JVM argument to JAVA_OPTS in the startup.sh file. 
    -Djava.security.properties=/path/to/custom-java.security

    The following example shows Entrust-specific entries in a custom java.security file:

    security.provider.13=nCipherKM
security.provider.14=BouncyCastleProvider
jdk.security.provider.preferred=Signature.RSASSA-PSS:nCipherKM, \
                                Signature.HS256:nCipherKM, \
                                Signature.HS384:nCipherKM, \
                                Signature.HS512:nCipherKM, \

    The jdk.security.provider.preferred setting is required for TLSv1.2 and TLSv1.3 handshakes.

Install and configure the External Keystore feature on all containers

Use the automation recipe or Admin Console user interface to install and configure an external keystore for Policy Manager and Network Director containers.

Option 1: Entrust HSM External Keystore configuration by using an automation recipe

When configuring an Entrust HSM as an external keystore by using an automation recipe, use the following Entrust HSM property values. For more information, see Using the External Keystore recipe to install and configure an external keystore.

Entrust nFast client version 13.6.15 is certified compatible with Akana Platform version 2024.1.4 and later.

Entrust HSM property configuration

Add the following Entrust HSM property values to your container properties file.

EX_KEYSTORE_PROVIDERNAME=nCipherKM
EX_KEYSTORE_KEYSTORETYPE=nCipher.sworld
EX_KEYSTORE_ENCRYPTED=true
EX_KEYSTORE_LOCATION=file:///opt/akana/etc/keystore.dat
EX_KEYSTORE_PASSWORD=your-entrust-hsm-password

Option 2: Install the External Keystore feature by using the Admin Console

For a newly created container, install and configure the External Keystore feature before you configure the container identity.

Install the External Keystore feature

  1. Launch the Akana Administration Console (http://<hostname>:<port>/admin/) for the container.
  2. On the Available Features tab, select Plug-in from the filter list.
  3. Select External Keystore.
  4. Select Install Feature.
  5. If prompted, restart the container.

Repeat these steps for each container that references the Entrust keystore, including Policy Manager and Network Director.

Configure the External Keystore feature

  1. In the Akana Administration Console, go to the Configuration tab.
  2. Select Configuration Actions > Configure External Keystore.
  3. In the External Keystore Options page, specify the following values:
    • Provider Name: nCipherKM
    • Keystore Type: nCipher.sworld
    • Keystore Location: The path to the HSM keystore.
    • Keystore Password: The Entrust OCS or module passphrase, if you configured either one.
  4. Set the Encrypted option:
    • Selected: Policy Manager attaches an alias. Network Director uses the alias to retrieve the private key directly from the external keystore.
    • Cleared: Policy Manager attaches the encrypted private key directly to the WSDL.
  5. Select Finish.
  6. If prompted, restart the container.

Repeat these steps for the Network Director container. Use the same values or Entrust-specific alias values if Network Director uses a different Security World. See Assigning Keys by Identity Type.

Update the container startup script

In <INSTALL_HOME>/bin/setDEMSEnv.sh, update AKANA_OPTS to include the Entrust HSM-specific JVM arguments:

AKANA_OPTS="${AKANA_OPTS} -Djava.security.properties=<path_to_custom_java_security> --module-path <entrust_nfast_java_path>"

Replace the following with values from your Entrust configuration:

  • <path_to_custom_java_security>: Full path to your custom Java security properties file (For example, /home/user/custom_java.security).
  • <entrust_nfast_java_path>: Path to Entrust nFast Java classes (typically, /opt/nfast/java/classes).

Alternatively, you can append the Entrust HSM arguments to the JAVA_OPTS in <INSTALL_HOME>/bin/startup.sh:

JAVA_OPTS="-Xmx4092M -Djavax.net.ssl.trustStore=<path_to_hsm_truststore> -Djava.security.properties=file:<path_to_custom_java_security> --module-path <entrust_nfast_java_path>"

Where:

  • <path_to_hsm_truststore>: Full path to your HSM trust store (For example, /home/user/hsm_trusted_cacerts.jks).
  • <path_to_custom_java_security>: Full path to your custom Java security properties file (For example, /home/user/java21security/java.security).
  • <entrust_nfast_java_path>: Path to Entrust nFast Java classes (typically, /opt/nfast/java/classes).

Verify the external provider installation

After completing the configuration, verify that the external provider is installed and that sensitive key information is not stored in the database.

  1. Restart the system.
  2. Log in to the Akana Administration Console for the container and go to the Configuration tab > Manage PKI Keys.
  3. On the Manage PKI screen, verify that the Assign alias option is available.

Assign keys

After you install the External Keystore feature, Generate PKI Keys and Export Private Keys and X.509 Certificate are not allowed for any identities requiring private keys. Private key material cannot be exported from the Entrust HSM.

For instructions on assigning keys to containers, listeners, services, organizations, users, and SAML SSO identities, see Assigning Keys by Identity Type.

The keystore password is optional for an Entrust HSM.

Signing and encryption provider configuration (JOSE and OAuth)

For information about configuring the Entrust HSM signing provider, see Signing provider for JOSE and OAuth.

Use nCipherKM as the provider value in the following fields:

  • JOSE Security Policy v2: In Crypto Provider, specify nCipherKM.
  • JOSE Profile-Driven Security Policy: In Crypto Provider, specify nCipherKM.
  • OAuth Client Policy: In Signing JCA Provider, specify nCipherKM.
  • Akana OAuth/OIDC Provider Domain: In Signing JCA Provider, Encrypt JCA Provider, and Decrypt JCA Provider, specify nCipherKM.
  • External OAuth Provider Domain: In Decrypt JCA Provider, specify nCipherKM.

If you need to use Bouncy Castle as a fallback for algorithms that Entrust does not support, follow the fallback-provider instructions in Signing provider for JOSE and OAuth.