Preparing an External HSM for the ActivID Appliance

Configure the HSM and the RFS

This section describes the basic configuration steps to configure the HSM and RFS.

For complete instructions, refer to the technical documentation provided with your HSM.

1. On the HSM:

   1. Configure the Ethernet interface (IP address/netmask of the HSM) and leave the link speed set to auto/1Gb (HSM menu 1-1-1-1).

   2. Set the default gateway (HSM menu 1-1-1-3).

   3. “Ping” or “Trace route” the RFS and the ActivID Appliance(s) (menu 1-1-1-6 or 1-1-1-7).

2. On the RFS:

   1. Install the Security World Software.

      The following is an example of a shell script to automate the installation if the Security World Software payload (for example, folder “linux/libc6_11”) is copied into the <NSHIELD_DISTRIB> folder defined in the script.

      Copy

      #!/bin/sh
       
      NSHIELD_DISTRIB=/WORK/nShieldConnect
      NFAST_HOME=/opt/nfast
       
      # Create nfast and ncsnmpd system users
      useradd -r -m -d $NFAST_HOME -s /bin/bash -c "nFast" nfast
      useradd -r -m -d $NFAST_HOME -s /bin/bash -c "nFast" ncsnmpd
       
      # untar distribution
      cd /
      find $NSHIELD_DISTRIB -name '*.tar' -exec /bin/tar xf '{}' \;
       
      # install
      $NFAST_HOME/sbin/install || {
          echo "fail to install nShield Connect Security World Software"
      }
       
      chown -R nfast:nfast $NFAST_HOME

   2. Add a firewall rule to open 9004 inbound TCP port.

   3. Switch to the nfast user account.

      Copy

      su - nfast

   4. Check that the HSM is operational using the following command (output of the command should show “mode operational” for the “Server” section):

      Copy

      ./enquiry

   5. Retrieve the ESN and keyhash of the HSM using the following command:

      Copy

      anonkneti <HSM-IP>

      Copy

      For example:

      ./anonkneti 10.16.96.149
      FFDF-E4F6-9787 b4cdac0cb25c2326c3de1886b8fb205d119529f0

   6. Create the RFS directory structure using the following command:

      Copy

      rfs-setup --force <HSM-IP> <HSM-ESN> <HSM-KNETI-hash>

      Copy

      For example:

      $> rfs-setup --force 10.16.96.149 FFDF-E4F6-9787 b4cdac0cb25c2326c3de1886b8fb205d119529f0
      Adding read-only remote_file_system entries
      Ensuring the directory /opt/nfast/kmdata/local exists
      Adding new writable remote_file_system entries
      Ensuring the directory /opt/nfast/kmdata/hsm-FFDF-E4F6-9787 exists
      Ensuring the directory /opt/nfast/femcerts exists
      Ensuring the directory /opt/nfast/kmdata/hsm-FFDF-E4F6-9787/features exists
      Ensuring the directory /opt/nfast/kmdata/hsm-FFDF-E4F6-9787/config exists
      Ensuring the directory /opt/nfast/log/hsm-FFDF-E4F6-9787 exists
      Saving the new config file and configuring the hardserver
      Done

3. On the HSM:

   1. Configure the HSM to use the RFS by entering the IP address of the RFS machine and leaving the port number as the default (9004) (HSM menu 1-1-3).

   2. (Optional) Allow HSM configuration files on the RFS to be modified and then loaded to the module by turning on the auto push (HSM menu 1-1-6-2).

   3. Configure the HSM log file storage and append the option to allow storing the log files on the RFS and HSM (HSM menu 1-1-7).

   4. Set the time and date as UTC (HSM menu 1-1-8).

   5. Add the RFS and the ActivID Appliance(s) as HSM clients by entering the remote client IP address and setting the client permission to unprivileged (HSM menu 1-1-4-1).

   6. Create a new security world FIPS 140-2 level 3 and Cipher suite AES (HSM menu 3-2-1).

      At this point, the Administrator Card Set (ACS) is created:

      • Each card set consists of a number of smart cards, N, of which a smaller number, K, is required to authorize an action. The required number K is known as the quorum.

      • For the ACS, the value for K should be less than N and not equal to 1.

4. On the RFS:

   1. Verify that the security world data is present locally using the following command:

      Copy

      ls –l /opt/nfast/kmdata/local

      For example, the output with a security world present is:

      Copy

      -rw-r--r-- 1 nfast nfast   128 Jul 23 09:38 card_849a96545928fa28759273fad3272961c42a4657_1
      -rw-r--r-- 1 nfast nfast   808 Jul 23 09:38 cards_849a96545928fa28759273fad3272961c42a4657
      -rw-r--r-- 1 nfast nfast   856 Jul 22 14:22 module_FFDF-E4F6-9787
      drwxrwsr-x 2 nfast nfast  4096 Jul 22 16:38 sync-store
      -rw-r--r-- 1 nfast nfast 17964 Jul 22 14:22 world

   2. As the nfast user account, use the following commands to:

      • Configure the TCP socket for Entrust KeySafe™ utility usage:

        Copy

        config-serverstartup --enable-tcp --enable-privileged-tcp

      • Configure RFS to use the HSM as unprivileged client:

        Copy

        nethsmenroll -V <HSM-IP> <HSM-ESN> <HSM-KNETI-hash>

   3. As the root user account, restart the HSM local agent (hardserver) using the following command:

      Copy

      /opt/nfast/sbin/init.d-ncipher restart

Creating the HSM Keys and Certificates

Before you can migrate to an external HSM and add ActivID security domains, you must create the following keys/certificates in the external HSM:

• ActivID Appliance keys – a set of five AES-256 keys used to protect sensitive information and assure integrity of data in the ActivID Appliance database

  The keys are managed in consistent key set for the following roles:

  • AUDIT – Audit signature

  • CREDS – User credentials are encrypted with the key role (replaces the des and DeviceSecretsKey keys of previous versions of the ActivID Appliance)

  • DSIGN – Database row integrity signature (DataSignature)

  • SESSION – sessions (ALSI)

  • SYS – System credentials (adapter parameters) (replaces the ParameterValueKey key of previous versions of the ActivID Appliance)

  Key Alias Naming Convention

  The following naming convention is used for the key aliases:

  <PREFIX>.<Key Role Type>.<version>

  Where:

  • <PREFIX> – to make sure that the names remain unique, a specific prefix 'HID-IA-4T’ is used for all the ActivID Appliance key aliases. This prefix is not configurable.

  • <Key Role Type> – is mandatory and is part of the key set (see previous list).

  • <Version> – number version of the key (incremented with renewal).

  Based on this convention, the default key set (shared by all domains) that you need to create using the HSM tools (ksafe or generatekey for nShield) BEFORE migrating the ActivID Appliance to the External HSM is:

  Key Role	Key Type	Alias – shared
  AUDIT	AES 256	HID-IA-4T.AUDIT.1
  CREDS	AES 256	HID-IA-4T.CREDS.1
  DSIGN	AES 256	HID-IA-4T.DSIGN.1
  SESSION	AES 256	HID-IA-4T.SESSION.1
  SYS	AES 256	HID-IA-4T.SYS.1

  Note: ActivID Appliance server expects the key aliases to be in uppercase characters as defined by the naming convention. However, case-sensitivity in keystores is (soft or HSM) implementation dependent. Therefore, when the HSM keys are created or renewed using a manual process (using HSM dependent tools), it is recommended that you always use the uppercase key aliases.

• IDP keys/certificates – for each ActivID security domain, the following RSA-2048 key/certificate pairs are used for SAML support:

  • IDP Signature RSA-2048 key/certificate – certificate key usage should be “Digital Signature”.

  • IDP Encryption RSA-2048 key/certificate – certificate key usage should be “Key Encipherment” and “Data Encipherment”.

Create the ActivID Appliance Keys

Before installing the ActivID Appliance, you must create the HSM encryption keys that protect the sensitive information in the ActivID databases and assure database integrity.

ActivID Appliance supports the following levels of key protection:

• Module-protected keys

• OCS-protected keys (using Operator Card Sets)

Create the ActivID Database keys using the Entrust KeySafe utility or command line utility (for further information, refer to the technical documentation provided with your HSM):

The following are examples to create module-protected keys.

Using the KeySafe utility:

1. As the nfast user account, launch the KeySafe utility (<NFAST_HOME>/bin/ksafe).

2. Click Keys in the left panel, and then click Create.

3. Select PKCS#11 in the applications list and then click Next.

4. Enter the following properties:

   • Protected by – module

   • Key recovery: yes

   • Key type – AES

   • Key size – 256

   • Key name: <keyname>

   • Blob in NVRAM – No

5. Click Commit.

Using the command line utility:

As the nfast user account, create the keys using the following command:

<NFAST_HOME>/bin/generatekey pkcs11 type=AES size=256 protect=module nvram=no plainname=<keyname>

Create the Operator Card Sets

The Operator Card Set is required to recover ActivID Appliance domain administrator users (ftadmin and ftinit).

Optionally, create and Operator Card set (or re-use an existing set) to protect the ActivID Appliance keys.

For instructions, refer to the technical documentation provided with your HSM.

Creating the ActivID IDP Keys/Certificates

The following PKCS#11 keys names (aliases) should be created in the HSM for each security domain:

• IDP_CERT_SIGNATURE_<domain>

• IDP_CERT_ENCRYPTION_<domain>

Each key should be created with the following properties:

• Key type – RSA

• Key size – 2048

• Protected by – module

• Blob in NVRAM – No

Create a Self-Signed IDP Certificate

1. To configure ‘openssl’ for IDP certificates key usage, edit the <NFAST_HOME>/lib/ssleay/openssl.cnf file by adding the following sections:

   Copy

   [ idp_encryption ]
   keyUsage = dataEncipherment, keyEncipherment
    
   [ idp_signature ]
   keyUsage = digitalSignature

   Note: From this point on, the “openssl” utility is used with either the -extensions idp_encryption or -extensions idp_signature option depending on the IDP certificate type (encryption or signature).

2. Generate an RSA key pair for the Crypto Hardware Interface Library (CHIL) application.

   The hwcrhk parameter value is the application name for the CHIL applications.

   Copy

   <NFAST_HOME>/bin/generatekey hwcrhk type=RSA size=2048 protect=module nvram=no ident=idpcertencryptionMyDomain
   OPTIONAL: pubexp: Public exponent for RSA key (hex)? []
   >
   key generation parameters:
   operation   Operation to perform             generate
   application Application                            hwcrhk
   protect       Protected by                          module
   verify          Verify security of key             yes
   type            Key type                                RSA
   size            Key size                                 2048
   pubexp      Public exponent for RSA key (hex)
   ident          Key identifier                         idpcertencryptionmydomain
   nvram        Blob in NVRAM (needs ACS)    no
    
   Key successfully generated.
   Path to key: /opt/nfast/kmdata/local/key_hwcrhk_rsa-idpcertencryptionmydomain

   This temporary key is generated with lowercase domain name, and not the original case.

3. Generate the self-signed certificate using “openssl”:

   Copy

   export LD_LIBRARY_PATH=<NFAST_HOME>/toolkits/hwcrhk
   <NFAST_HOME>/bin/openssl req -new -days 1825 –sha256 -engine chil \
      -config <NFAST_HOME>/lib/ssleay/openssl.cnf \
      -extensions idp_encryption \
      -key rsa-idpcertencryptionmydomain -keyform engine -x509 \
      -out /tmp/IDP_CERT_ENCRYPTION_MyDomain.pem \
      -subj "/OU=MyDomain/O=HID/CN=ACTIVID IDP Encryption"
   engine "chil" set.

   Note:

   • In the example, the IDP encryption certificate duration is set to 5 years (1825 days).

   • The “key” corresponds to temporary key created in previous step (lowercase). However, for the output, you must specify your <domain> name with correct case.

4. Duplicate the RSA key pair for PKCS#11 application:

   Copy

   <NFAST_HOME>/bin/generatekey --retarget pkcs11 from-application=hwcrhk plainname=IDP_CERT_ENCRYPTION_MyDomain
   from-ident: Source key identifier? (rsa-idpcertencryptionmydomain)
     [default rsa-idpcertencryptionmydomain] >
   key generation parameters:
   operation             Operation to perform    retarget
   application           Application                   pkcs11
   verify                   Verify security of key     yes
   from-application  Source application         hwcrhk
   from-ident           Source key identifier      rsa-idpcertencryptionmydomain
   plainname            Key name                      IDP_CERT_ENCRYPTION_MyDomain
   Key successfully retargetted.
   Path to key: /opt/nfast/kmdata/local/key_pkcs11_ua59677affe039c8ab700772b93c99a812da690357

   This generates a PKCS#11 key pair identifier that is the value following the key_pkcs11_” value in the “Path to key displayed by the above command. In this example, ua59677affe039c8ab700772b93c99a812da690357

5. Retrieve the key pair identifier (for sanity checks):

   Copy

   <NFAST_HOME>/bin/cklist -n --cka-label=IDP_CERT_ENCRYPTION_MyDomain | grep CKA_NFKM_ID
     CKA_NFKM_ID "ua59677affe039c8ab700772b93c99a812da690357"
     CKA_NFKM_ID "ua59677affe039c8ab700772b93c99a812da690357"

   The key pair identifier corresponding to the value of the “CKA_NFKM_ID” should match the value obtained in the previous step.

6. Import and bind the certificate to the key pair:

   Copy

   <NFAST_HOME>/bin/ckcerttool -n -f /tmp/IDP_CERT_ENCRYPTION_MyDomain.pem -k ua59677affe039c8ab700772b93c99a812da690357 –L IDP_CERT_ENCRYPTION_MyDomain
    
   Certificate found, processing...
   Certificate successfully imported.
   Run cklist to view your certificate object.
   OK

7. Using the Entrust KeySafe utility, remove the RSA key pair (identified by idpcertencryptionmydomain) created above as it is no longer needed.

8. Repeat the steps above to create the IDP signature certificate (IDP_CERT_SIGNATURE_MyDomain).

Create a CA Trusted IDP Certificate

1. From the RFS, generate key pair and certificate request:

   Using the KeySafe utility

   1. Launch the KeySafe utility (<NFAST_HOME>/bin/ksafe).

   2. Click Keys in the left panel, and then click Create.

   3. Select PKCS#11 with certificate request (RSA only) in the applications list and click Next.

   4. Enter the following properties:

      • Protected by – module

      • Key recovery: yes

      • Key size – 2048

      • Public exponent for RSA key (hex):

      • Filename to write key to: <path>/<IDP_CERT_XXX_YYY>

      • Key name: <IDP_CERT_XXX_YYY>

      • Country code: <your value>

      • State or province: <your value>

      • City or locality: <your value>

      • Organisation: <your value>

      • Organisation unit: <your value>

      • Domain name: <your value>

      • Email address: <your value>

      • Blob in NVRAM – No

   5. Click Commit.

   6. In the Load FIPS Authorization page, click OK and, if required, insert your operator or administrator card into the HSM.

   7. Click OK and then click Commit.

   8. Click OK.

      The following certificate request file is created in the <path> folder:

      <IDP_CERT_XXX_YYY>_req

   9. In the Keys page, select the <IDP_CERT_XXX_YYY> key in the Key List and identify the Key Instance/Copy id information (for example, <IDP_CERT_XXX_YYY_KEYID> as in the subsequent steps).

   Using command line utilities

   1. Generate the key pair and the certificate request.

      Copy

      <NFAST_HOME>/bin/generatekey pkcs11 type=RSA size=2048 protect=module nvram=no certreq=yes plainname=<IDP_CERT_XXX_YYY>

   2. Provide the parameters as illustrated below.

      

      The following certificate request file is created in the <path> folder of the Filename to write key to parameter (“/tmp” in the example above):

      <IDP_CERT_XXX_YYY>_req

   3. In the “Path to key” displayed in the console, identify the value displayed after the key_pkcs11_ pattern (in the following steps, this is <IDP_CERT_XXX_YYY_KEYID>).

2. Obtain the certificate from the CA and upload it in PEM format:

   1. Submit the certificate request (<IDP_CERT_XXX_YYY>_req) to the CA.

      Important: Make sure that you request the IDP certificate with the correct key usage.

   2. Upload the PEM format of the certificate into the <path> folder on the RFS.

      For example, if a “.CER” format has to be obtained from a Microsoft Windows CA, then:

      • Copy the <filename>.cer file into the <path> folder on the RFS.

      • Use the following openssl command to convert it to a PEM format:

        Copy

        openssl x509 -inform der -in <path>/<filename>.cer -outform pem -out <path>/<IDP_CERT_XXX_YYY>.pem

3. From the RFS, import and bind the certificate to the key pair:

   1. Import and bind the certificate to the key pair:

      Copy

      <NFAST_HOME>/bin/ckcerttool -n -f /<path>/<IDP_CERT_XXX_YYY>.pem -k <IDP_CERT_XXX_YYY_KEYID> -L <IDP_CERT_XXX_YYY>
       
      Certificate found, processing...
      Certificate successfully imported.
      Run cklist to view your certificate object.
      OK

   2. Check the HSM content:

      Copy

      <NFAST_HOME>/bin/cklist -n --cka-label=IDP_CERT_XXX_YYY | grep CKA_CLASS
        CKA_CLASS CKO_PUBLIC_KEY
        CKA_CLASS CKO_PRIVATE_KEY
        CKA_CLASS CKO_CERTIFICATE

Renewing an IDP Certificate

To renew an IDP certificate, the data related to this certificate (key pair and certificate) should be removed from the HSM before creating the new data.