Chapter 3. Integrating OpenStack Key Manager (barbican) with Hardware Security Module (HSM) appliances

Integrate your Red Hat OpenStack Platform deployment with hardware security module (HSM) appliances to increase your security posture by using hardware based cryptographic processing. When you plan your OpenStack Key Manager integration with an HSM appliance, you must choose a supported encryption type and HSM appliance, set up regular backups, and review any other information or limitations that might affect your deployment.

3.1. Integrating OpenStack Key Manager (barbican) with an Atos HSM

To integrate the PKCS#11 back end with your Trustway Proteccio Net HSM appliance, create a configuration file with the parameters to connect barbican with the HSM. You can enable HA by listing two or more HSMs below the atos_hsms parameter.

Planning

By default, the HSM can have a maximum of 32 concurrent connections. If you exceed this number, you might experience a memory error from the PKCS#11 client. You can calculate the number of connections as follows:

  • Each Controller has one barbican-api and one barbican-worker process.
  • Each Barbican API process is executed with N Apache workers - (where N defaults to the number of CPUs).
  • Each worker has one connection to the HSM.

Each barbican-worker process has one connection to the database. You can use the BarbicanWorkers heat parameter to define the number of Apache workers for each API process. By default, the number of Apache workers matches the CPU count.

For example, if you have three Controllers, each with 32 cores, then the Barbican API on each Controller uses 32 Apache workers. Consequently, one Controller consumes all 32 HSM connections available. To avoid this contention, limit the number of Barbican Apache workers configured for each node. In this example, set BarbicanWorkers to 10 so that all three Controllers can make ten concurrent connections each to the HSM.

Prerequisites

  • A password-protected HTTPS server that provides vendor software for the Atos HSM

Table 3.1. Files provided by the HTTPS server

FileExampleProvided by

Proteccio Client Software ISO image file

Proteccio1.09.05.iso

HSM Vendor

SSL server certificate

proteccio.CRT

HSM administrator

SSL client certificate

client.CRT

HSM administrator

SSL Client key

client.KEY

HSM administrator

Procedure

  1. Create a configure-barbican.yaml environment file for Barbican and add the following parameters: 

    parameter_defaults
  BarbicanSimpleCryptoGlobalDefault: false
  BarbicanPkcs11CryptoGlobalDefault: true
  BarbicanPkcs11CryptoLogin: ********
  BarbicanPkcs11CryptoSlotId: 1
  ATOSVars:
    atos_client_iso_name: Proteccio1.09.05.iso
    atos_client_iso_location: https://user@PASSWORD:example.com/Proteccio1.09.05.iso
    atos_client_cert_location: https://user@PASSWORD:example.com/client.CRT
    atos_client_key_location: https://user@PASSWORD:example.com/client.KEY
    atos_hsms:
      - name: myHsm1
        server_cert_location: https://user@PASSWORD:example.com/myHsm1.CRT
        ip: 192.168.1.101
      - name: myHsm2
        server_cert_location: https://user@PASSWORD:example.com/myHsm2.CRT
        ip: ip: 192.168.1.102
    Note

    The atos_hsms parameter supersedes the parameters atos_hsm_ip_address and atos_server_cert_location which have been deprecated and will be removed in a future release.

    Table 3.2. Heat parameters

    ParameterValue

    BarbicanSimpleCryptoGlobalDefault

    This is a Boolean that determines if simplecrypto is the global default.

    BarbicanPkcs11GlobalDefault

    This is a Boolean that determines if PKCS#11 is the global default.

    BarbicanPkcs11CryptoSlotId

    Slot ID for the Virtual HSM to be used by Barbican.

    ATOSVars

    atos_client_iso_name

    The filename for the Atos client software ISO. This value must match the filename in the URL for the atos_client_iso_location parameter.

    atos_client_iso_location

    The URL, including the username and password, that specifies the HTTPS server location of the Proteccio Client Software ISO image.

    atos_client_cert_location

    The URL, including the username and password, that specifies the HTTPS server location of the SSL client certificate.

    atos_client_key_location

    The URL, including the username and password, that specifies the HTTPS server location of the SSL client key. This must be the matching key for the client certificate above.

    atos_hsms

    A list of one or more HSMs that specifies the name, certificate location and IP address of the HSM. When you include more than one HSM in this list, Barbican configures the HSMs for load balancing and high availability.

  2. Include the custom configure-barbican.yaml, barbican.yaml and ATOS specific barbican-backend-pkcs11-atos.yaml environment files in the deployment command, as well as any other environment files relevant to your deployment: 

    $ openstack overcloud deploy \
    --timeout 100 \
    --templates /usr/share/openstack-tripleo-heat-templates \
    --stack overcloud \
    --libvirt-type kvm \
    --ntp-server clock.redhat.com \
    -e /home/stack/containers-prepare-parameter.yaml \
    -e /home/stack/templates/config_lvm.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml \
    -e /home/stack/templates/network/network-environment.yaml \
    -e /home/stack/templates/hostnames.yml \
    -e /home/stack/templates/nodes_data.yaml \
    -e /home/stack/templates/extra_templates.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/services/barbican.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/barbican-backend-pkcs11-atos.yaml \
    -e /home/stack/templates/configure-barbican.yaml \
    --log-file overcloud_deployment_with_atos.log

Verification

  1. Create a test secret: 

    $ openstack secret store --name testSecret --payload 'TestPayload'
+---------------+------------------------------------------------------------------------------------+
| Field         | Value                                                                              |
+---------------+------------------------------------------------------------------------------------+
| Secret href   | https://192.168.123.163/key-manager/v1/secrets/4cc5ffe0-eea2-449d-9e64-b664d574be53 |
| Name          | testSecret                                                                         |
| Created       | None                                                                               |
| Status        | None                                                                               |
| Content types | None                                                                               |
| Algorithm     | aes                                                                                |
| Bit length    | 256                                                                                |
| Secret type   | opaque                                                                             |
| Mode          | cbc                                                                                |
| Expiration    | None                                                                               |
+---------------+------------------------------------------------------------------------------------+

  2. Retrieve the payload for the secret that you just created: 

    openstack secret get https://192.168.123.163/key-manager/v1/secrets/4cc5ffe0-eea2-449d-9e64-b664d574be53 --payload
+---------+-------------+
| Field   | Value       |
+---------+-------------+
| Payload | TestPayload |
+---------+-------------+

3.2. Integrating OpenStack Key Manager (barbican) with a Thales Luna Network HSM

To integrate the PKCS#11 back end with your Thales Luna Network HSM appliance for hardware based cryptographic processing, use an Ansible role to download and install the Thales Luna client software on the Controller, and create a Key Manager configuration file to include the predefined HSM IP and credentials.

Prerequisites

  • A password-protected HTTPS server that provides vendor software for the Thales Luna Network HSM.
  • The vendor provided Luna Network HSM client software in a compressed zip archive.

Procedure

  1. Install the ansible-role-lunasa-hsm role on the director: 

    sudo dnf install ansible-role-lunasa-hsm

  2. Create a configure-barbican.yaml environment file for Key Manager (barbican) and add parameters specific to your environment. 

    parameter_defaults:
  BarbicanPkcs11CryptoMKEKLabel: "barbican_mkek_0"
  BarbicanPkcs11CryptoHMACLabel: "barbican_hmac_0"
  BarbicanPkcs11CryptoLogin: "$PKCS_11_USER_PIN"
  BarbicanPkcs11CryptoGlobalDefault: true
  LunasaVars:
    lunasa_client_tarball_name: 610-012382-014_SW_Client_HSM_6.2_RevA.tar.zip
    lunasa_client_tarball_location: https://user:$PASSWORD@http-server.example.com/luna_software/610-012382-014_SW_Client_HSM_6.2_RevA.tar.zip
    lunasa_client_installer_path: 610-012382-014_SW_Client_HSM_6.2_RevA/linux/64/install.sh
    lunasa_hsms:
      - hostname: luna-hsm.example.com
        admin_password: "$HSM_ADMIN_PASSWORD"
        partition: myPartition1
        partition_serial: 123456789

    Table 3.3. Heat parameters

    ParameterValue

    BarbicanSimpleCryptoGlobalDefault

    This is a Boolean that determines if simplecrypto is the global default.

    BarbicanPkcs11GlobalDefault

    This is a Boolean that determines if PKCS#11 is the global default.

    BarbicanPkcs11CryptoTokenLabel

    If you have one HSM, then the value of the parameter is the partition Label. If you are using HA between two or more partitions, then this is the label that you want to give to the HA group.

    BarbicanPkcs11CryptoLogin

    The PKCS#11 password used to log into the HSM, provided by the HSM administrator.

    LunasaVar

    lunasa_client_tarball_name

    The name of the Luna software tarball.

    lunasa_client_tarball_location

    The URL that specifies the HTTPS server location of the Luna Software tarball.

    lunasa_client_installer_path

    Path to the install.sh script in the zipped tarball.

    lunasa_client_rotate_cert

    (Optional) When set to true, new client certificates will be generated to replace any existing certificates. Default: false

    lunasa_client_working_dir

    (Optional) Working directory in the Controller nodes. Default: /tmp/lunasa_client_install

    lunasa_hsms

    A list of one or more HSMs that specifies the name, hostname, admin_password, partition, and partition serial number. When you include more than one HSM in this list, Barbican configures the HSMs for high availability.

  3. Include the custom configure-barbican.yaml and Thales specific barbican-backend-pkcs11-llunasa.yaml environment files in the deployment command, as well as any other templates relevant for your deployment: 

    $ openstack overcloud deploy --templates \
  ....
  -e /usr/share/openstack-tripleo-heat-templates/environments/services/barbican.yaml \
  -e /usr/share/openstack-tripleo-heat-templates/environments/barbican-backend-pkcs11-lunasa.yaml \
  -e /home/stack/templates/configure-barbican.yaml \
  --log-file overcloud_deployment_with_luna.log

3.3. Integrating OpenStack Key Manager (barbican) with an Entrust nShield Connect XC HSM

To integrate the PKCS#11 back end with your Entrust nShield Connect XC HSM, use an Ansible role to download and install the Entrust client software on the Controller, and create a Barbican configuration file to include the predefined HSM IP and credentials.

Prerequisites

  • A password-protected HTTPS server that provides vendor software for the Entrust nShield Connect XC.

Procedure

  1. Create a configure-barbican.yaml environment file for Barbican and add parameters specific to your environment. Use the following snippet as an example: 

        parameter_defaults:
        SwiftEncryptionEnabled: true
        ComputeExtraConfig:
            nova::glance::verify_glance_signatures: true
    nova::compute::verify_glance_signatures: true
        BarbicanPkcs11CryptoLogin: 'sample string'
        BarbicanPkcs11CryptoSlotId: '492971158'
        BarbicanPkcs11CryptoGlobalDefault: true
        BarbicanPkcs11CryptoLibraryPath: '/opt/nfast/toolkits/pkcs11/libcknfast.so'
        BarbicanPkcs11CryptoEncryptionMechanism: 'CKM_AES_CBC'
        BarbicanPkcs11CryptoHMACKeyType: 'CKK_SHA256_HMAC'
        BarbicanPkcs11CryptoHMACKeygenMechanism: 'CKM_NC_SHA256_HMAC_KEY_GEN'
        BarbicanPkcs11CryptoMKEKLabel: 'barbican_mkek_10'
        BarbicanPkcs11CryptoMKEKLength: '32'
        BarbicanPkcs11CryptoHMACLabel: 'barbican_hmac_10'
        BarbicanPkcs11CryptoThalesEnabled: true
        BarbicanPkcs11CryptoEnabled: true
        ThalesVars:
            thales_client_working_dir: /tmp/thales_client_install
            thales_client_tarball_location: https://your server/CipherTools-linux64-dev-12.40.2.tgz
            thales_client_tarball_name: CipherTools-linux64-dev-12.40.2.tgz
            thales_client_path: linux/libc6_11/amd64/nfast
            thales_client_uid: 42481
            thales_client_gid: 42481
            thales_km_data_location: https://your server/kmdata_post_card_creation.tar.gz
            thales_km_data_tarball_name: kmdata_post_card_creation.tar.gz
            thales_hsm_ip_address: 192.168.10.10
            thales_rfs_server_ip_address: 192.168.10.11
            thales_hsm_config_location: hsm-C90E-02E0-D947
            thales_rfs_user: root
            thales_rfs_key: |
                -----BEGIN RSA PRIVATE KEY-----
Sample private key
-----END RSA PRIVATE KEY-----

resource_registry:
    OS::TripleO::Services::BarbicanBackendPkcs11Crypto: /home/stack/tripleo-heat-templates/puppet/services/barbican-backend-pkcs11-crypto.yaml

    Table 3.4. Heat parameters

    ParameterValue

    BarbicanSimpleCryptoGlobalDefault

    This is a Boolean that determines if simplecrypto is the global default.

    BarbicanPkcs11GlobalDefault

    This is a Boolean that determines if PKCS#11 is the global default.

    BarbicanPkcs11CryptoSlotId

    Slot ID for the Virtual HSM to be used by Barbican.

    BarbicanPkcs11CryptoMKEKLabel

    This parameter defines the name of the mKEK generated in the HSM. Director creates this key in the HSM using this name.

    BarbicanPkcs11CryptoHMACLabel

    This parameter defines the name of the HMAC key generated in the HSM. Director creates this key in the HSM using this name.

    ThalesVars

    thales_client_working_dir

    A user-defined temporary working directory.

    thales_client_tarball_location

    The URL that specifies the HTTPS server location of the Entrust software.

    thales_km_data_tarball_name

    The name of the Entrust software tarball.

    thales_rfs_key

    A private key used to obtain an SSH connection to the RFS server. You must add this as an authorized key to the RFS server.

  2. Include the custom configure-barbican.yaml environment file, along with the barbican.yaml and Thales specific barbican-backend-pkcs11-thales.yaml environment files, and any other templates needed for you deployment when running the openstack overcloud deploy command: 

    $ openstack overcloud deploy \
    --timeout 100 \
    --templates /usr/share/openstack-tripleo-heat-templates \
    --stack overcloud \
    --libvirt-type kvm \
    --ntp-server clock.redhat.com \
    -e /home/stack/containers-prepare-parameter.yaml \
    -e /home/stack/templates/config_lvm.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml \
    -e /home/stack/templates/network/network-environment.yaml \
    -e /home/stack/templates/hostnames.yml \
    -e /home/stack/templates/nodes_data.yaml \
    -e /home/stack/templates/extra_templates.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/services/barbican.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/barbican-backend-pkcs11-thales.yaml \
    -e /home/stack/templates/configure-barbican.yaml \
    --log-file overcloud_deployment_with_atos.log

Verification

  1. Create a test secret: 

    $ openstack secret store --name testSecret --payload 'TestPayload'
+---------------+------------------------------------------------------------------------------------+
| Field         | Value                                                                              |
+---------------+------------------------------------------------------------------------------------+
| Secret href   | https://192.168.123.163/key-manager/v1/secrets/4cc5ffe0-eea2-449d-9e64-b664d574be53 |
| Name          | testSecret                                                                         |
| Created       | None                                                                               |
| Status        | None                                                                               |
| Content types | None                                                                               |
| Algorithm     | aes                                                                                |
| Bit length    | 256                                                                                |
| Secret type   | opaque                                                                             |
| Mode          | cbc                                                                                |
| Expiration    | None                                                                               |
+---------------+------------------------------------------------------------------------------------+

  2. Retrieve the payload for the secret that you just created: 

    openstack secret get https://192.168.123.163/key-manager/v1/secrets/4cc5ffe0-eea2-449d-9e64-b664d574be53 --payload
+---------+-------------+
| Field   | Value       |
+---------+-------------+
| Payload | TestPayload |
+---------+-------------+

3.4. Rotating MKEK and HMAC keys

You can rotate the MKEK and HMAC keys using a director update.

Note

Due to a limitation in Barbican, the MKEK and HMAC have the same key type.

Procedure

  1. Add the following parameter to your deployment environment files: 

    BarbicanPkcs11CryptoRewrapKeys:          true

  2. Change the labels on the MKEK and HMAC keys For example, if your labels are similar to these: 

            BarbicanPkcs11CryptoMKEKLabel: 'barbican_mkek_10'
        BarbicanPkcs11CryptoHMACLabel: 'barbican_hmac_10'

    You can change the labels by incrementing the values: 

            BarbicanPkcs11CryptoMKEKLabel: 'barbican_mkek_11'
        BarbicanPkcs11CryptoHMACLabel: 'barbican_hmac_11'
    Note

    Do not change the HMAC key type.

  3. Re-deploy using director to apply the update. Director checks whether the keys that are labelled for the MKEK and HMAC exist, and then creates them. In addition, with the BarbicanPkcs11CryptoRewrapKeys parameter set to True, director calls barbican-manage hsm pkek_rewrap to rewrap all existing pKEKs.