Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 7. Installing an IdM deployment with keys and certificates stored on an HSM

A hardware security module (HSM) provides a hardened, tamper-resistant environment for secure cryptographic processing, key generation, and encryption. You can store your key pairs and certificates for your IdM Certificate Authority (CA) and Key Recovery Authority (KRA) on an HSM. This adds physical security to the private key material.

IdM relies on the networking features of the HSM to share the keys between machines to create replicas. The HSM provides additional security without visibly affecting most IdM operations. When you use low-level tooling, the system handles certificates and keys differently, but this is seamless for most users.

Important

Note the following:

  • The HSM must be connected to a network.
  • The private keys cannot leave the device.
  • You cannot mix what is stored on an HSM. For example, you cannot install the KRA private keys on an HSM without also installing the CA private keys on it.
  • If you use an HSM on the initial installation, then all replicas and KRAs must also use the same HSM.
  • You cannot upgrade an existing installation where the keys were not generated on an HSM to an HSM-based install.

Using an HSM is largely invisible to users and administrators beyond passing additional options during the installation. The options required and any pre-installation work are HSM-specific.

7.1. Supported hardware security modules

The following table lists hardware security modules (HSM) supported by Identity Management (IdM):

HSMFirmwareAppliance SoftwareClient Software

nCipher nShield Connect XC (High)

nShield_HSM_Firmware-12.72.1

12.71.0

SecWorld_Lin64-12.71.0

Thales TCT Luna Network HSM Luna-T7

lunafw_update-7.11.1-4

7.11.0-25

610-500244-001_LunaClient-7.11.1-5

7.2. Installing an IdM server with an integrated CA with keys and certificates stored on an HSM

The default configuration for the ipa-server-install command is an integrated CA as the root CA.

During the installation, you must supply basic configuration of the system, for example the realm, the administrator’s password and the Directory Manager’s password.

The ipa-server-install installation script creates a log file at /var/log/ipaserver-install.log. If the installation fails, the log can help you identify the problem.

Prerequisites

  • A supported networked HSM installed set up according to its vendors instructions. See Supported HSMs.
  • The HSM PKCS #11 library path, /opt/nfast/toolkits/pkcs11/libcknfast.so.
  • An available slot, token, and the token password.

Procedure

  1. Run the install command, ensuring you specify the location of the PKCS #11 library, the token name, and the token password: 

    ipa-server-install -a <password> -p <dmpassword>-r <IDM.EXAMPLE.COM> -U --setup-dns --allow-zone-overlap --no-forwarders -N --auto-reverse --random-serial-numbers -–token-name=<HSM-TOKEN> --token-library-path=/opt/nfast/toolkits/pkcs11/libcknfast.so
    Copy to Clipboard
  2. Specify the token password when prompted.

Verification

  1. Run certutil to display CA certificate information: 

    certutil -L -d /etc/pki/pki-tomcat/alias

Certificate Nickname                    Trust Attributes
                                        SSL,S/MIME,JAR/XPI

caSigningCert cert-pki-ca               CT,C,C
ocspSigningCert cert-pki-ca             ,,
Server-Cert cert-pki-ca                 u,u,u
subsystemCert cert-pki-ca               ,,
auditSigningCert cert-pki-ca            ,,P
    Copy to Clipboard

    Note that where there is no u listed under Trust Attributes for a certificate, it indicates the private keys are stored on the token. In this case, only the Server-Cert cert-pki-ca has the u flags as it is not installed on the HSM for performance reasons.

  2. Verify that the keys and certificates are stored on the HSM: 

    certutil -L -d /etc/pki/pki-tomcat/alias -h <HSM-TOKEN>

Certificate Nickname                                Trust Attributes
	   SSL,S/MIME,JAR/XPI

Enter Password or Pin for "<HSM-TOKEN>":
<HSM-TOKEN>:subsystemCert cert-pki-ca                  	u,u,u
<HSM-TOKEN>:ocspSigningCert cert-pki-ca                	u,u,u
<HSM-TOKEN>:caSigningCert cert-pki-ca                  	CTu,Cu,Cu
<HSM-TOKEN>:auditSigningCert cert-pki-ca               	u,u,Pu
    Copy to Clipboard

    The certificate name is prefixed with the HSM token name, which indicates that the private keys and certificates are stored on the token.

    Where the keys are stored does not affect how users obtain or use certificates.

7.3. Installing an IdM server with an external CA with keys and certificates stored on an HSM

You can install a new Identity Management (IdM) server that uses an external certificate authority (CA) as a root CA.

During the installation, you must supply basic configuration of the system, for example the realm, the administrator’s password and the Directory Manager’s password.

The ipa-server-install installation script creates a log file at /var/log/ipaserver-install.log. If the installation fails, the log can help you identify the problem.

Prerequisites

  • A supported networked HSM installed set up according to its vendors instructions. See Supported HSMs.
  • The HSM PKCS #11 library path, /opt/nfast/toolkits/pkcs11/libcknfast.so.
  • An available slot, token, and the token password.

  • If you install a server without an integrated IdM CA, you must request the following certificates from a third-party authority:

    • An LDAP server certificate
    • An Apache server certificate
    • A PKINIT certificate
    • Full CA certificate chain of the CA that issued the LDAP and Apache server certificates

Procedure

  1. Run the install command, ensuring you specify that you are using an external CA. 

    # ipa-server-install --external-ca
    Copy to Clipboard

    During the installation process, the utility prints the location of the certificate signing request (CSR) /root/ipa.csr: 

    ...

Configuring certificate server (pki-tomcatd): Estimated time 3 minutes 30 seconds
  [1/8]: creating certificate server user
  [2/8]: configuring certificate server instance
The next step is to get /root/ipa.csr signed by your CA and re-run /sbin/ipa-server-install as:
/sbin/ipa-server-install --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate
    Copy to Clipboard

  2. To complete the certificate process, using the CSR generated by the installation utility, complete the following steps:

    1. Submit the CSR located in /root/ipa.csr to the external CA. The process differs depending on the service to be used as the external CA.

    2. Retrieve the issued certificate and the CA certificate chain for the issuing CA in a base 64-encoded blob (either a PEM file or a Base_64 certificate from a Windows CA). Again, the process differs for every certificate service. Usually, a download link on a web page or in the notification email allows the administrator to download all the required certificates.

      Important

      Obtain the full certificate chain for the CA, not just the CA certificate.

  3. Run the ipa-server-install utility again to specify the path and names of the newly-issued CA certificate and the CA chain files and the location of the PKCS #11 library, the token name, and the token password: 

    # ipa-server-install --external-cert-file=</tmp/servercert20170601.pem> --external-cert-file=</tmp/cacert.pem> -–token-name=<HSM-TOKEN> --token-library-path=/opt/nfast/toolkits/pkcs11/libcknfast.so
    Copy to Clipboard
  4. Specify the token password when prompted.
  5. The installation script now configures the server. Wait for the operation to complete.

Verification

  1. Run certutil to display CA certificate information: 

    certutil -L -d /etc/pki/pki-tomcat/alias

Certificate Nickname                    Trust Attributes
                                        SSL,S/MIME,JAR/XPI

caSigningCert cert-pki-ca               CT,C,C
ocspSigningCert cert-pki-ca             ,,
Server-Cert cert-pki-ca                 u,u,u
subsystemCert cert-pki-ca               ,,
auditSigningCert cert-pki-ca            ,,P
    Copy to Clipboard

    You can see the certificates but the ,, indicates no private keys as they are stored on the token.

  2. Verify that the keys and certificates are stored on the HSM: 

    certutil -L -d /etc/pki/pki-tomcat/alias - h <HSM-TOKEN>

Certificate Nickname                                Trust Attributes
	   SSL,S/MIME,JAR/XPI

Enter Password or Pin for "<HSM-TOKEN>":
<HSM-TOKEN>:subsystemCert cert-pki-ca                  	u,u,u
<HSM-TOKEN>:ocspSigningCert cert-pki-ca                	u,u,u
<HSM-TOKEN>:caSigningCert cert-pki-ca                  	CTu,Cu,Cu
<HSM-TOKEN>:auditSigningCert cert-pki-ca               	u,u,Pu
    Copy to Clipboard

    The certificate name is prefixed with the HSM token name, which indicates that the private keys and certificates are stored on the token.

    Where the keys are stored does not affect how users obtain or use certificates.

7.4. Installing an IdM replica server with keys and certificates stored on an HSM

The replica installation process copies the configuration of the existing server and installs the replica based on that configuration.

Prerequisites

Procedure

  1. Run the install command, ensuring you specify the token name: 

    # ipa-replica-install --token-name=<HSM-TOKEN> --setup-ca -P admin -w <password> -U
    Copy to Clipboard
  2. Specify the token password when prompted.

Verification

  • Verify that the keys and certificates are stored on the HSM: 

    certutil -L -d /etc/pki/pki-tomcat/alias - h <HSM-TOKEN>

Certificate Nickname                                Trust Attributes
	   SSL,S/MIME,JAR/XPI

Enter Password or Pin for "<HSM-TOKEN>":
<HSM-TOKEN>:subsystemCert cert-pki-ca                  	u,u,u
<HSM-TOKEN>:ocspSigningCert cert-pki-ca                	u,u,u
<HSM-TOKEN>:caSigningCert cert-pki-ca                  	CTu,Cu,Cu
<HSM-TOKEN>:auditSigningCert cert-pki-ca               	u,u,Pu
    Copy to Clipboard

    The certificate name is prefixed with the HSM token name, which indicates that the private keys and certificates are stored on the token.

    Where the keys are stored does not affect how users obtain or use certificates.

7.5. Installing a KRA server with keys and certificates stored on an HSM

To enable vaults in RHEL Identity Management (IdM), install the Key Recovery Authority (KRA) Certificate System (CS) component on a specific IdM server.

Prerequisites

  • The token password.

Procedure

  1. Run the install command, ensuring you specify the token name and the token password: 

    # ipa-kra-install -p <password>
    Copy to Clipboard
  2. Specify the token password when prompted.

Verification

  • Verify that the keys and certificates are stored on the HSM: 

    certutil -L -d /etc/pki/pki-tomcat/alias - h <HSM-TOKEN>

Certificate Nickname                                Trust Attributes
	   SSL,S/MIME,JAR/XPI

Enter Password or Pin for "<HSM-TOKEN>":
<HSM-TOKEN>:subsystemCert cert-pki-ca                  	u,u,u
<HSM-TOKEN>:ocspSigningCert cert-pki-ca                	u,u,u
<HSM-TOKEN>:caSigningCert cert-pki-ca                  	CTu,Cu,Cu
<HSM-TOKEN>:auditSigningCert cert-pki-ca               	u,u,Pu
<HSM-TOKEN>:storageCert cert-pki-kra                           u,u,u
<HSM-TOKEN>:transportCert cert-pki-kra                         u,u,u
<HSM-TOKEN>:auditSigningCert cert-pki-kra                      u,u,Pu
    Copy to Clipboard

    The certificate name is prefixed with the HSM token name, which indicates that the private keys and certificates are stored on the token.

    Where the keys are stored does not affect how users obtain or use certificates.

7.6. Installing a KRA clone with keys and certificates stored on an HSM

By default an IdM replica does not have a KRA, unless you specified the --setup-kra option during the IdM client promotion.

Prerequisites

  • The token password.
  • A KRA server installed.

Procedure

  1. To install a KRA clone, execute the following command on the replica: 

    # ipa-kra-install -p <Secret.123 >
    Copy to Clipboard
  2. Specify the token password when prompted.

Verification

  • Verify that the keys and certificates are stored on the HSM: 

    certutil -L -d /etc/pki/pki-tomcat/alias - h <HSM-TOKEN>

Certificate Nickname                                Trust Attributes
	   SSL,S/MIME,JAR/XPI

Enter Password or Pin for "<HSM-TOKEN>":
<HSM-TOKEN>:subsystemCert cert-pki-ca                  	u,u,u
<HSM-TOKEN>:ocspSigningCert cert-pki-ca                	u,u,u
<HSM-TOKEN>:caSigningCert cert-pki-ca                  	CTu,Cu,Cu
<HSM-TOKEN>:auditSigningCert cert-pki-ca               	u,u,Pu
<HSM-TOKEN>:storageCert cert-pki-kra                           u,u,u
<HSM-TOKEN>:transportCert cert-pki-kra                         u,u,u
<HSM-TOKEN>:auditSigningCert cert-pki-kra                      u,u,Pu
    Copy to Clipboard

    The certificate name is prefixed with the HSM token name, which indicates that the private keys and certificates are stored on the token.

    Where the keys are stored does not affect how users obtain or use certificates.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat