The following provides step-by-step instructions on how to integrate EJBCA and deploy Engage Black’s BlackVault HSM. The instructions are created utilizing the BlackVault Hardware Security Module (HSM) with a touchpad. 

Initialize BlackVault HSM

The following outlines the steps required to initialize a BlackVault HSM device, equipped with a touchscreen display.

Preparation and Planning

The following covers what you need to prepare and plan before you begin:

  • Gather the required number of secure crypto cards for both the Crypto Officer and User roles. The required number of cards will depend on the number of Crypto Officer and User cards that will be assigned to custodians.
  • Role Types:
    • Crypto Officer: Account for HSM administration only, cannot be used to manage certificates
    • User: Account for managing certificates only.
  • Each role will use a separate set of crypto cards for authorization.
  • (M of N cards required to access HSM, minimum is 1 of 1 for each role)

Initialize HSM

To initialize the HSM, perform the following steps:

  1. Power up the HSM unit.
  2. Begin the initialization sequence by following the on-screen pages. (warning) The first few pages are informational. Press OK when prompted to proceed.
  3. Use FIPS Mode Prompt:
    • If FIPS compliance is required, click Yes.
    • Otherwise, click No to continue.
  4. Import Smart Card Database:
    • For first-time initialization, click No to skip.
  5. Crypto Officer smart card set:
    • Specify the number of Crypto Officer (CO) crypto cards required to log in (M of N, minimum 1 of 1):
      • Enter the number of cards in total to create.
      • Enter the number of cards required to log in.
    • Click Done.
  6. Enter PIN for Crypto Card 1:
    • Enter a PIN using the touchscreen soft keyboard and press ENTER to continue (min: 4 characters).
    • Re-enter the PIN to verify and press ENTER.
  7. Crypto Officer Creation - Insert card number 1:
    • Insert a blank crypto card into the HSM card slot.
    • Verify the on-screen serial number with that printed on the physical crypto card.
    • Record the crypto card serial number and its assigned use and custodian (for example, Crypto Officer Crypto Card #1 assigned to John Doe) in a separate document for future reference.
    • Click Yes if the serial numbers match
    • Repeat setting PINs for the remaining Crypto Officer crypto cards.
  8. Login as Crypto Officer required to proceed.:
    1. After all CO crypto cards have been assigned, log in as the Crypto Officer using M of N cards.
  9. User Creation - User card set:
    • Specify the number of user crypto cards required to log in (M of N, minimum 1 of 1)
    • Enter the number of cards in total to create.
    • Enter the number of cards required to log in.
    • Click Done.
  10. Enter PIN for User Card 1:
    • Enter a PIN using the touchscreen soft keyboard and press ENTER to continue (Minimum Length Requirement: 4 characters)
    • Re-enter the PIN to verify and press ENTER.
  11. User Creation - Insert card number 1:
    • Insert a blank crypto card into the HSM card slot.
    • Verify the on-screen serial number with that printed on the physical crypto card.
    • Record the crypto card serial number and its assigned use and custodian (for example, User Crypto Card #1 assigned to Jane Doe) in a separate document for future reference.
    • Click Yes if the serial numbers match.
    • Repeat setting PINs for the remaining User crypto cards.
  12. Initialization - completed successfully:
    • Click OK to complete initialization. (warning) Initialization will not be completed until OK is clicked.

Configure HSM Settings

To configure the HSM settings, do the following:

  1. Log into the HSM as Crypto Officer and click Settings.
  2. Click Date Setting:
    • Enter current date and click Save.
    • Click OK.
  3. Click Time Setting:
    • Enter current time and click Save.
    • Click OK.
  4. Click Time zone Setting:
    • In the first field, select the continental region.
    • After a region is selected, a second field showing available time zones will appear. Select the appropriate time zone and click Save.
    • Click OK.
  5. Scroll down for additional settings and click Network Configuration:
    • Enter the HSM’s IP address.
    • Enter the HSM’s subnet mask.
    • Enter the HSM’s default gateway and click Save.
    • Click OK.

Back Up HSM

There are two databases to back up on the BlackVault HSM, the Smart Card Export (Crypto Officer and User credentials) and the User Database (Certificates).

Requirements

  • Minimum of 4 crypto cards, 2 for the User Database and 2 for Smart Card Export. (N of M cards required for authorization of data restoration, 2 of 2 minimum for each).
  • USB flash drive, formatted with one of the following: ext2, ext3, FAT32, or VFAT. (USB drive capacity dependent on the size of User Database and Smart Card Export).
  • Crypto cards for both Crypto Officer and User to log onto the HSM.

Back Up User Database

To back up the user database, do the following:

  1. Log in to the HSM as User.
  2. Select System Commands.
  3. Select User Database Backup.
  4. Insert USB drive.
  5. Create User Database Backup card set (N of M, minimum 2 of 2).
  6. Note serial numbers of the crypto cards used for the Backup card set.
  7. Answer Yes for "Allow Restore of backup only with this User card set?"
  8. Insert User Database encryption key smart cards as prompted. Answer Yes if prompted to overwrite data on the smart card.
  9. Log out of the HSM.

Export Smart Card

To export the smart card, do the following:

  1. Log in to the HSM as Crypto Officer.
  2. Select System Commands.
  3. Select Smart Card Database Export.
  4. Insert USB drive.
  5. Create Export card set (N of M, minimum 2 of 2).
  6. Note serial numbers of the crypto cards used for the Export card set.
  7. Insert Smart Card Database Export smart cards as prompted. Answer Yes if prompted to overwrite data on the smart card.
  8. Log out of the HSM.

Restore/Clone HSM

The BlackVault HSM backup data can be used to either restore an existing HSM or clone a duplicate HSM on separate hardware.

Requirements

  • Minimum set of smart cards for authorization for both the Crypto Officer and User.
  • USB drive containing the Crypto Card Export and User Database backup data.
  • Smart Card Export and User Database Backup crypto card sets.

Restore HSM

To restore the HSM, do the following:

  1. Zeroize HSM unit to reset to factory default state, if necessary (to repurpose a previously configured HSM).
  2. Begin the initialization sequence by following the on-screen pages. (warning) The first few pages are informational. Press OK when prompted to proceed.
  3. Use FIPS Mode Prompt:
    • If FIPS compliance is required, click Yes.
    • Otherwise, click No to continue.
  4. Import Smart Card Database:
    • When prompted to Import Smart Card Database, click Yes.
  5. Follow the prompts to insert the USB drive and insert required (M of N) Encryption Key Export smart cards.
  6. Insert the Crypto Officer card and verify credentials when prompted.
  7. After restoring the smart card database, the HSM will reboot.
  8. Log in to the HSM as User.
    (warning) Logging in successfully also serves as verification that the Smart Card Database was properly restored/cloned.
  9. Select System Commands.
  10. Select User Database Restore.
  11. Follow the prompts to insert the USB drive and insert required (M of N) User Database Backup smart cards.

Verify User Database

To verify the user database:

  • On a workstation with BlackVault client software installed, run the bvtool to verify that the certificates have been restored:

    bvtool list -a
    CODE

EJBCA Integration Procedure

The following provides steps for the EJBCA integration.

Prerequisites

  • BlackVault HSM, initialized and configured properly. Refer to the BlackVault HSM User Guide for more information.
  • Determine the EJBCA installation type. BlackVault HSM is supported on EJBCA Software Appliance and EJBCA Software installations.
    • The host must be running Java 8 and configured with EJBCA.
  • Network port TCP 5002 is allowed between EJBCA host and BlackVault HSM
  • Elevated privileges are required on EJBCA Host.
  • BlackVault Card Set
    • Crypto Users HSM card set and credentials
  • BlackVault HSM Setup CD or Download area for driver package access

Install Driver

The following provides instructions for installing the driver and utilizes the CentOS RPM (bvhsm-7.0.47-1.x86_64.rpm).

To install the driver:

  1. Download the appropriate installation package or extract it from the BlackVault HSM Setup CD.

  2. Install the RPM:

    yum install bvhsm-7.0.47-1.x86_64.rpm
    BASH

  3. Create a pkcs.dat file and add the line below. (warning) Ensure to replace the HSM IP as applicable. The default port is 5002.

    vi /opt/ejbca/pkcs.dat

192.168.1.10 5002
    BASH

  4. Update the EJBCA variable. For an EJBCA software installation, it will be /opt/ejbca/.profile.

    vi /etc/profile.d/ejbcaenv.sh

#Add this line
export BV_PKCS_PATH="/opt/ejbca/pkcs.dat"
    BASH

  5. Update the WildFly environment variable:

    vi /etc/wildfly/wildfly.conf
		
#Add this line
BV_PKCS_PATH="/opt/ejbca/pkcs.dat"
    BASH

  6. Update the EJBCA properties file:

    vi /opt/ejbca/conf/web.properties
		
#Add these values
# Available PKCS#11 CryptoToken libraries and their display names
# If a library file's presence is not detected it will not show up in the Admin GUI.
# Default values (see src/java/defaultvalues.properties for most up to date values):
cryptotoken.p11.lib.1.name=BlackVault
cryptotoken.p11.lib.1.file=/usr/lib64/libbvpkcs.so
    BASH

  7. Restart Wildfly:

    sudo systemctl restart wildlfly
    BASH

  8. Test HSM connectivity with the following bvtool command to list keys in the HSM:

    bvtool list -a
    BASH

Set up EJBCA Crypto Token and CA

To create a crypto token in EJBCA, do the following:

  1. Open a browser and go to the URL https://fqdn:8443/ejbca/adminweb to access EJBCA.
  2. Select Crypto Tokens under CA Functions, and then click Create new.
  3. Enter the following on the New Crypto Token page:
    • Name: Enter RootCA-CryptoToken
    • Type: Select PKCS#11
    • Authentication Code: Enter the password for the slot (password from HSM user card)
    • Repeat Authentication Code: Re-enter the password
    • PKCS#11 : Library: Select BlackVault
      • PKCS#11 Reference Type: Select Slot ID
    • In the PKCS#11 Reference list, enter 1
  4. Click Save.
  5. Create three key pairs within the Crypto Token on the Crypto Token: <Name> page:
    • Enter signKey as the name for the new key, choose ECDSA P-256 / prime256v1 / secp256r from the list, and click Generate new key pair.
    • Click Test for the new key created, the result should be signKey tested successfully.
    • Enter defaultKey as the name for the new key, choose ECDSA P-256 / prime256v1 / secp256r from the list, and click Generate new key pair.
    • Click Test for the new key created, the result should be defaultKey tested successfully.
    • Enter testKey as the name for the new key, choose ECDSA P-256 / prime256v1 / secp256r from the list, and click Generate new key pair.
    • Click Test for the new key created, the result should be testKey tested successfully.

The keys are now created and the crypto token can be used to create a CA certificate profile and CA. For more information, see Managing Certificate Profiles and Managing CAs.

Additional Resources

To get started with the BlackVault HSM, refer to how-to videos available on Engage Black videos.

For more information on EJBCA CA, see Certificate Authority Overview.