Uploaded image for project: 'OpenIDM'
  1. OpenIDM
  2. OPENIDM-5832

Document how to set up OpenIDM to work with an HSM provider

    XMLWordPrintable

Details

    • New Feature
    • Status: Closed
    • Major
    • Resolution: Fixed
    • OpenIDM 5.0.0
    • OpenIDM 5.0.0
    • documentation

    Description

      HSM (hardware security module) is an alternative keystore – since it's based on Customer hardware, they'll want to provide the keystore, instead of using something generated via OpenIDM or from a CA.

      The rest of this is from the following PR

      1. HSM Configuration
        1. Setup a HSM Provider
          1. Installation
            For HSM to work the user needs access to an HSM device or a software emulation of an hsm device. In my testing I chose to use [Softhsm2](https://www.opendnssec.org/softhsm/) to test hsm support. Softhsm2 is available on various systems as a [package](https://www.opendnssec.org/download/packages/).

      For OSX, you can install Softhsm2 using brew with the following command:
      ```
      brew install softhsm
      ```

          1. Configure the Provider
            Once Softhsm2 is installed you then need to create an environment variable to the softhsm2 configuration like so:
            ```
            export SOFTHSM2_CONF=/usr/local/Cellar/softhsm/2.0.0/etc/softhsm2.conf
            ```

      I pointed to the default softhsm configuration. The configuration file looks like this:
      ```

      1. SoftHSM v2 configuration file

      directories.tokendir = /usr/local/Cellar/softhsm/2.0.0/var/lib/softhsm/tokens/
      objectstore.backend = file

      1. ERROR, WARNING, INFO, DEBUG
        log.level = INFO
        ```

      The settings are pretty simple. The only thing you might want to change is the location there the tokens are installed, directories.tokendir.

          1. Initialize the Prodiver
            Finally you need to initialize a slot on the hsm device. This can be done with the following command:
            ```
            softhsm2-util --init-token --slot 0 --label "My token 1"
            ```
            softhsm2-util is a program that was installed when you install softhsm2. This initialization will ask you to enter 2 pins a SO PIN and a user PIN. It is important to remember these values.
          1. Create the Hsm Configuration File
            The PKCS11 standard uses a configuration file to interact with the HSM device. The file should have some basic configuration settings as described [here](https://docs.oracle.com/javase/7/docs/technotes/guides/security/p11guide.html#Config). Two settings that are required are the name and library setting. The name is a suffix to identify the hsm provider, and the library is the providers pkcs11 implementation. The configuraiton file I used looked like this:
            ```
            name = softHSM
            library = /usr/local/Cellar/softhsm/2.0.0/lib/softhsm/libsofthsm2.so
            slot = 0
            attributes(generate, *, *) = { CKA_TOKEN = true }

            attributes(generate, CKO_CERTIFICATE, *) =

            { CKA_PRIVATE = false }
            attributes(generate, CKO_PUBLIC_KEY, *) = { CKA_PRIVATE = false }

            ```

        1. Populate the Default Encryption Keys
          1. Generate the openidm-sym-default Encryption Key
            OpenIDM uses by default a AES key called openidm-sym-default to encrypt data stored in OpenIDM. With an HSM provider this key must be generated manually. This key can be generated with the following command:
            ```
            keytool -genseckey -alias openidm-sym-default -keyalg AES -keysize 128 -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg ~/Desktop/hsm/hsm.conf
            ```
          1. Generate the openidm-localhost Certificate (Optional)
            The following steps will generate the openidm-localhost certificate, which is used by OpenIDM to support SSL/TLS. This step is optional and only nessesary if you want to put the truststore on the HSM. My steps will not require the truststore to be setup on the HSM.
            ```
            openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 360
            openssl pkcs12 -export -in cert.pem -inkey key.pem -certfile cert.pem -out testkeystore.p12

      keytool -importkeystore -srckeystore testkeystore.p12 -srcstoretype PKCS12 -destkeystore NONE -deststoretype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg ~/Desktop/hsm/hsm.conf

      keytool -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg ~/Desktop/hsm/hsm.conf -list

      keytool -changealias -alias 1 -destalias openidm-localhost -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg ~/Desktop/hsm/hsm.conf
      ```

        1. Configure OpenIDM
          1. Configure OpenIDM Keystore
            To configure OpenIDM to use the HSM provider for the keystore the following properties need to be set in the conf/boot/boot.properties file.
            ```
            openidm.keystore.type=PKCS11
            openidm.keystore.provider=SunPKCS11-softHSM
            openidm.keystore.location=none
            openidm.security.pkcs11.config=/path/to/hsm.conf
            openidm.keystore.password=<HSM SO Pin>
            ```
          1. Configure OpenIDM Truststore (Optional)
            To configure OpenIDM to use the HSM provider for the truststore the following properties need to be set in the conf/boot/boot.properties file.
            ```
            openidm.truststore.type=PKCS11
            openidm.truststore.provider=SunPKCS11-softHSM
            openidm.truststore.location=none
            openidm.security.pkcs11.config=/path/to/hsm.conf
            openidm.truststore.password=<HSM SO Pin>
            ```

      Attachments

        Issue Links

          Activity

            People

              Lana Lana Frost
              Mike2 Mike Jang [X] (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: