Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 5. Barbican Hardware Security Module (HSM) Integration

OpenStack Key Manager (Barbican) is the secrets manager for Red Hat OpenStack Platform. You can use the Barbican API and command line to centrally manage the certificates, keys, and passwords used by OpenStack services. Barbican currently supports the following use cases described in this guide:

  • Symmetric encryption keys - used for Block Storage (cinder) volume encryption, ephemeral disk encryption, Object Storage (Sswift) encryption, among others.
  • Asymmetric keys and certificates - glance image signing and verification, octavia TLS load balancing, among others.

In this release, Barbican offers integration with the Block Storage (cinder), Networking (neutron), and Compute (nova) components.

barbican key flow

5.1. Choosing a backend

Secrets (such as certificates, API keys, and passwords) can either be stored as an encrypted blob in the Barbican database, directly in a secure storage system, including a Hardware Security Module (HSM) appliance.

5.2. Encrypted blob

The simple crypto plugin is enabled by default and uses a single symmetric key to encrypt the blob of secrets. This key is stored in plain text in the barbican.conf file.

5.3. Hardware Security Module (HSM) support

You can use the PKCS#11 crypto plugin to store the secrets in a Hardware Security Module (HSM), which are physical rack-mounted appliances produced by third party vendors. These secrets are encrypted using the pKEK, which in turn is also stored in the Barbican database. The pKEK is encrypted and an HMAC operation is applied using the MKEK and HMAC keys, which are also stored in the HSM.

This guide explains how to integrate Barbican with certain HSM appliances from Atos and nCipher.

You can use the following approaches to interact with an HSM:

  • PKCS#11 crypto plugin - The PKCS#11 crypto plugin encrypts secrets with project-specific key encryption keys (KEK), which are stored in the Barbican database. These project-specific KEKs are encrypted by a master KEK. The encrypted blob containing the PKEK also undergoes HMAC processing by an HMAC key, which is also stored in the HSM. All encryption and decryption operations take place in the HSM, rather than in-process memory. The PKCS#11 plugin communicates with the HSM through the PKCS#11 protocol. Because the encryption is performed in secure hardware, and a different KEK is used per project, this option is more secure than the simple crypto plugin.
  • KMIP plugin - Note that this approach is not supported by Red Hat. The Key Management Interoperability Protocol (KMIP) plugin works with devices that have KMIP enabled, such as an HSM. Secrets are stored directly on the device instead of the Barbican database. The plugin can authenticate to the device either with a username and password or a client certificate stored in the barbican.conf file.
Note

Regarding high availability (HA) options: The Barbican service runs within Apache and is configured by director to use HAProxy for high availability. Your HA options for the backend layer will depend on the which backend is used: For example, with simple crypto, all the Barbican instances have the same encryption key in the configuration file, resulting in a simple HA configuration.

5.4. Migrating between backends

Barbican allows you to define a different backend for a project. If no mapping exists for a project, then secrets are stored in the global default backend. This means that multiple backends can be configured, but there must be only one global backend defined. The heat templates supplied for the different backends contain the parameters that set each backend as the default.

If you do store secrets in a certain backend and then decide to migrate to a new backend, you can keep the old backend available while enabling the new backend as the global default (or as a project-specific backend). As a result, the old secrets remain available through the old backend.

5.5. Integrate with an HSM appliance

This chapter explains how to integrate your Red Hat OpenStack Platform deployment with certain HSM appliances. It also describes general operational procedures that you will need to consider.

5.6. Integrate Barbican with an Atos HSM

This section explains how to integrate the PKCS#11 backend with your Trustway Proteccio NetHSM appliance.

5.7. Requirements

  • A working Barbican deployment in your Red Hat OpenStack Platform environment.

  • Plan your HSM integration so that you have the following settings ready for the director deployment. These values will be entered into barbican-backend-pkcs11-atos.yaml (described in the following section).

    • BarbicanPkcs11CryptoLogin - the passphrase used by the PKCS#11 library (PIN).

    • Prior to installation, you must follow the ATOS procedures to generate a client certificate for the controllers. Host the client certificate, the server certificate, and the Atos client ISO file on an HTTP or FTP server that is accessible by the overcloud nodes. Some of this material is secret (such as client keys) and must be protected; if you use passwords to do this, you must provide the location as http://user:pass@location, or ftp://user:pass@location, among other possibilities. During the installation process, director invokes ansible scripts to retrieve these files. The file paths used in the following values must be accessible during the installation process.

      • atos_client_iso_location
      • atos_client_cert_location
      • atos_client_key_location
      • atos_server_cert_location
      • atos_client_working_dir
      • atos_client_iso_name
      • atos_hsm_ip_address

5.8. Configure the controller

This procedure uses an Ansible role to download and install the Atos client software on the controller, and then modifies the Atos configuration file to include to the predefined HSM IP and credentials.

  1. Create an environment file in OVERCLOUD_TEMPLATES named barbican-backend-pkcs11-atos.yaml, and enter the configuration details of your HSM. For example:

    Copy to Clipboard Toggle word wrap 
    tripleo_heat_templates:
    - /usr/share/openstack-tripleo-heat-templates/environments/services/barbican.yaml
    - /usr/share/openstack-tripleo-heat-templates/environments/barbican-backend-pkcs11-atos.yaml
custom_templates:
    parameter_defaults:
        SwiftEncryptionEnabled: true
        ComputeExtraConfig:
            nova::glance::verify_glance_signatures: true
            nova::compute::verify_glance_signatures: true
        BarbicanPkcs11CryptoLogin: 'sample string'
        BarbicanPkcs11CryptoSlotId: 1
        BarbicanPkcs11CryptoGlobalDefault: true
        BarbicanPkcs11CryptoLibraryPath: '/usr/lib64/libnethsm.so'
        BarbicanPkcs11CryptoEncryptionMechanism: 'CKM_AES_CBC'
        BarbicanPkcs11CryptoHMACKeyType: 'CKK_GENERIC_SECRET'
        BarbicanPkcs11CryptoHMACKeygenMechanism: 'CKM_GENERIC_SECRET_KEY_GEN'
        BarbicanPkcs11CryptoMKEKLabel: 'barbican_mkek_5a'
        BarbicanPkcs11CryptoMKEKLength: 32
        BarbicanPkcs11CryptoHMACLabel: 'barbican_hmac_5a'
        BarbicanPkcs11CryptoATOSEnabled: true
        BarbicanPkcs11CryptoEnabled: true
        ATOSVars:
            atos_client_working_dir: /tmp/atos_client_install
            atos_client_iso_location: https://your server/Proteccio1.09.03.iso
            atos_client_iso_name: Proteccio1.09.03.iso
            atos_client_cert_location: https://your server/proteccio_client.crt
            atos_client_key_location: https://your server/proteccio_client.key
            atos_server_cert_location: https://your server/192_168_11_13.crt
            atos_hsm_ip_address: 192.168.11.12
resource_registry:
    OS::TripleO::Services::BarbicanBackendPkcs11Crypto: /home/stack/tripleo-heat-templates/puppet/services/barbican backend-pkcs11-crypto.yaml
    • BarbicanPkcs11CryptoGlobalDefault and BarbicanPkcs11CryptoEnabled - These options configure PKCS#11 as the global default backend.
    • BarbicanPkcs11CryptoMKEKLabel - Defines the name of the mKEK generated in the HSM. Director creates this key in the HSM using this name. This name must be unique for every fresh installation, otherwise conflicts can occur if the same label name is used.

    • BarbicanPkcs11CryptoHMACLabel - Defines the name of the HMAC key generated in the HSM. Director creates this key in the HSM using this name.

      Note

      By default, the HSM allows a maximum of 32 concurrent connections. If this number is exceeded, you can expect to receive 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.

      BarbicanWorkers - Each barbican-worker process has one connection to the database; this setting lets you define the number of Apache workers per API process. By default, it matches the CPU count. This setting configures barbican::wsgi::apache::workers. The number of Barbican workers is controlled by the parameter queue/asynchronous_workers in barbican.conf, which defaults to 1. Currently there is no tripleO parameter to manage this value.

      For example, if you have three controllers, each with 32 cores, then each controller’s Barbican API uses 32 Apache workers (because BarbicanWorkers will default to 32). 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, setting BarbicanWorkers to 10 will allow all three controllers to make ten concurrent connections each to the HSM.

  2. Execute the script by adding the path to your existing openstack overcloud deploy command, and re-running it.

5.8.1. Test your HSM connection

  1. Create a test secret. For example:

    Copy to Clipboard Toggle word wrap 
    $ 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 you just created:

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

5.9. Integrate Barbican with an nCipher nShield Connect XC

This section explains how to integrate the PKCS#11 backend with your nCipher nShield Connect XC crypto backend.

  • A working Barbican deployment in your Red Hat OpenStack Platform environment.

  • Plan your HSM integration so that you have the following settings ready for the Ansible deployment. These values will be entered into barbican-backend-pkcs11-thales.yaml (described in the following section).

    • thales_client_working_dir and thales_client_tarball_location - The nCipher nShield Connect XC client software must be mounted in a location that it is accessible during the install. These values will vary depending on the file location and file names.
    • thales_client_working_dir - When the client software is unzipped, the location of the software may change the value.
    • thales_km_data_location and thales_km_data_tarball_name - These describe the security world data, and must also be mounted in an accessible location. This material is secret and must be protected; if you use passwords to do this, you must provide the location as http://user:pass@location, or ftp://user:pass@location, among other possibilities. During the installation process, director invokes ansible scripts to retrieve these files. The file paths used in the following values must be accessible during the installation process.
    • thales_rfs_key - The RFS server must be accessible to a user that has permission to login and execute commands that update the configuration. This allows you to add the controllers as HSM clients. The ansible scripts will ssh to the rfs server using the provided private key. The public key will need to be uploaded to the rfs server as an authorized key first.

5.10. Configure the controller

This procedure uses an Ansible role to download and install the nCipher client software on the controller, and then modifies the nCipher configuration file to include to the predefined HSM IP and credentials.

  1. Create an environment file in OVERCLOUD_TEMPLATES named barbican-backend-pkcs11-thales.yaml, and enter the configuration details of your nCipher nShield Connect XC. For example:

    Copy to Clipboard Toggle word wrap 
    tripleo_heat_templates:
    - /usr/share/openstack-tripleo-heat-templates/environments/services/barbican.yaml
    - /usr/share/openstack-tripleo-heat-templates/environments/barbican-backend-pkcs11-thales.yaml

custom_templates:
    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
    • BarbicanPkcs11CryptoGlobalDefault and BarbicanPkcs11CryptoEnabled - These options configure PKCS#11 as the global default backend.
    • BarbicanPkcs11CryptoMKEKLabel - Defines the name of the mKEK generated in the HSM. Director creates this key in the HSM using this name.

    • BarbicanPkcs11CryptoHMACLabel - Defines the name of the HMAC key generated in the HSM. Director creates this key in the HSM using this name.

      1. Execute the script by adding the path to your existing openstack overcloud deploy command, and re-running it.

5.10.1. Test your HSM connection

  1. Create a test secret. For example:

    Copy to Clipboard Toggle word wrap 
    $ 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 you just created:

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

5.11. Review TLS activity between Barbican and the HSM

Barbican communicates with the HSM through the vendor-provided PKCS#11 library. For example, for an ATOS Proteccio HSM, you can configure the HSM client to communicate with the HSM using TLS by configuring the proteccio.rc file.

For the Atos HSM, the files containing the CA, server certificate, and key are located on the controller, and are owned by the barbican user. Note that the barbican user does not exist on the controller, and is the barbican user as defined in the Barbican container. As a result, this is indicated in the file as a numerical identifier. The files should be readable for the barbican user (0400); these files are then bind mounted by the Barbican container.

For the nCipher nShield Connect XC, to view additional logs on the pkcs#11 transactions between the HSM and the client software, add the following entries to /opt/nfast/cknfastrc:

Copy to Clipboard Toggle word wrap 
CKNFAST_DEBUG=9
CKNFAST_DEBUGFILE=/tmp/hsm_log.txt

5.12. Key storage considerations

The Barbican MKEK and HMAC keys are generated using Barbican utilities that communicate with the HSM using the vendor’s PKCS#11 library. Therefore the MKEK and HMAC keys are generated in the HSM and never leave the HSM.

In a director-based deployment, these utilities are executed within containers on the first controller; the undercloud is never involved in this process.

5.13. Rotating the keys

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

Note

The MKEK and HMAC have the same key type. This is a limitation in Barbican, and is currently expected to be addressed at a later time.

  1. To rotate the keys, add the following parameter to your deployment environment files:

    Copy to Clipboard Toggle word wrap 
    BarbicanPkcs11CryptoRewrapKeys:          true

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

    Copy to Clipboard Toggle word wrap 
            BarbicanPkcs11CryptoMKEKLabel: 'barbican_mkek_10'
        BarbicanPkcs11CryptoHMACLabel: 'barbican_hmac_10'

    You can change the labels by incrementing the values:

    Copy to Clipboard Toggle word wrap 
            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.

5.14. Planning backup for Barbican and the HSM

The section describes the components you will need to consider when planning your Barbican and HSM backup strategy.

  • Barbican secrets - These are stored in the database, and must be backed up regularly.
  • MKEK and HMAC keys - These are stored in the HSM. Check with your HSM vendor for recommended practices.
  • HSM client certificates and keys - These are located on the controller, and must be included in your controller’s file backup procedure. Note that these files are sensitive credentials.
  • Barbican configuration files
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat, Inc.