Configuring IBM Security Guardium Key Lifecycle Manager with HSM

Configure Hardware Security Module (HSM) for storing the master key to protect all your data that is stored in the database.

When you configure IBM® Security Guardium® Key Lifecycle Manager with HSM, you might have one of the following installation setups:
  • A newly installed IBM Security Guardium Key Lifecycle Manager on which you have not created a server certificate or any data.
  • An existing installation of IBM Security Guardium Key Lifecycle Manager on which you already have a server certificate or some data.

Configuring HSM on a newly installed IBM Security Guardium Key Lifecycle Manager

  1. On the IBM Security Guardium Key Lifecycle Manager server, create an HSM configuration file. You can use the sample HSM configuration file for reference.
    1. Create the HSM client config file.
      Default location of the directory.
      Windows
      C:\Program Files\IBM\WebSphere\AppServer\products\sklm\config
      UNIX
      /opt/IBM/WebSphere/AppServer/products/sklm/config
    2. Only on UNIX systems, change the ownership of the HSM client config file to database user.
      For example, run the following step to change the ownership of the nCipher.cfg file to database user (klmdb42).
      chown klmdb42:klmdb42 nCipher.cfg
    3. In the HSM client config file, change the library parameter to point to the path of the HSM client library. For example, change the library parameter to point to the path of the nCipher library.
      Windows
      library=C:/nCipher/nfast/cknfast.dll
      UNIX
      library=/opt/nfast/toolkits/pkcs11/cknfast
  2. Add the following parameters to the IBM Security Guardium Key Lifecycle Manager configuration file SKLMConfig.properties.
    • pkcs11.pin
    • pkcs11.config
    • useMasterKeyInHSM
    You can use the following REST service to add the parameters.
    REST interface
    PUT https://localhost:port/SKLM/rest/v1/configProperties
    { "pkcs11.pin" : "hsm_pin"}
    PUT https://localhost:port/SKLM/rest/v1/configProperties
    { "pkcs11.config" : "hsm_config_file"}
    PUT https://localhost:port/SKLM/rest/v1/configProperties
    { "useMasterKeyInHSM" : "true | false"}
    Where
    • hsm_pin is the pin for HSM.

      Holds the pin that IBM Security Guardium Key Lifecycle Manager uses to connect to HSM. IBM Security Guardium Key Lifecycle Manager obfuscates the pin and places the obfuscated version back to the configuration file by using the pkcs11.pin.obfuscated property.

    • hsm_config_file is the full path and file name of the HSM configuration file. For example,
      Windows
      C:\Program Files\IBM\WebSphere\Liberty\sklm\config\hsm_config_file
      For example, C:\Program Files\IBM\WebSphere\Liberty\sklm\config\LunaSA.cfg.
      For example, C:\Program Files\IBM\WebSphere\Liberty\sklm\config\nCipher.cfg.
      Linux®
      /opt/IBM/WebSphere/Liberty/products/sklm/config/hsm_config_file
      For example, /opt/IBM/WebSphere/Liberty/products/sklm/config/LunaSA.cfg
      For example, /opt/IBM/WebSphere/Liberty/products/sklm/config/nCipher.cfg
  3. Restart IBM Security Guardium Key Lifecycle Manager.

Configuring HSM on an existing installation of IBM Security Guardium Key Lifecycle Manager

  1. On the IBM Security Guardium Key Lifecycle Manager server, create an HSM configuration file. You can use the sample HSM configuration file for reference.
    1. Create the HSM client config file.
      Default location of the directory.
      Windows
      C:\Program Files\IBM\WebSphere\AppServer\products\sklm\config
      UNIX
      /opt/IBM/WebSphere/AppServer/products/sklm/config
    2. Only on UNIX systems, change the ownership of the HSM client config file to database user.
      For example, run the following step to change the ownership of the nCipher.cfg file to database user (klmdb42).
      chown klmdb42:klmdb42 nCipher.cfg
    3. In the HSM client config file, change the library parameter to point to the path of the HSM client library. For example, change the library parameter to point to the path of the nCipher library.
      Windows
      library=C:/nCipher/nfast/cknfast.dll
      UNIX
      library=/opt/nfast/toolkits/pkcs11/cknfast
  2. Add the following parameters to the IBM Security Guardium Key Lifecycle Manager configuration file SKLMConfig.properties.
    • pkcs11.pin
    • pkcs11.config
    You can use the following REST service to add the parameters.
    REST interface
    PUT https://localhost:port/SKLM/rest/v1/configProperties
    { "pkcs11.pin" : "hsm_pin"}
    PUT https://localhost:port/SKLM/rest/v1/configProperties
    { "pkcs11.config" : "hsm_config_file"}
    Where
    • hsm_pin is the pin for HSM.

      Holds the pin that IBM Security Guardium Key Lifecycle Manager uses to connect to HSM. IBM Security Guardium Key Lifecycle Manager obfuscates the pin and places the obfuscated version back to the configuration file by using the pkcs11.pin.obfuscated property.

    • hsm_config_file is the full path and file name of the HSM configuration file. For example,
      Windows
      C:\Program Files\IBM\WebSphere\Liberty\sklm\config\hsm_config_file
      For example, C:\Program Files\IBM\WebSphere\Liberty\sklm\config\LunaSA.cfg.
      For example, C:\Program Files\IBM\WebSphere\Liberty\sklm\config\nCipher.cfg.
      Linux
      /opt/IBM/WebSphere/Liberty/products/sklm/config/hsm_config_file
      For example, /opt/IBM/WebSphere/Liberty/products/sklm/config/LunaSA.cfg
      For example, /opt/IBM/WebSphere/Liberty/products/sklm/config/nCipher.cfg
    Note: Ensure that the useMasterKeyInHSM parameter in the HSM configuration file is not set to true.
  3. Run the Master Key REST Service to move the master key that was used to encrypt the existing data from the Java keystore to the HSM server.
  4. Restart IBM Security Guardium Key Lifecycle Manager.

What to do next

Verify whether HSM is configured with IBM Security Guardium Key Lifecycle Manager. For more information, see Verifying HSM configuration.