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 File Example Provided 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 Create a configure-barbican.yaml environment file for Barbican and add the following parameters: 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 Parameter Value 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. 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: Verification Create a test secret: Retrieve the payload for the secret that you just created: 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 Install the ansible-role-lunasa-hsm role on the director: Create a configure-barbican.yaml environment file for Key Manager (barbican) and add parameters specific to your environment. Table 3.3. Heat parameters Parameter Value 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. 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: 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 Create a configure-barbican.yaml environment file for Barbican and add parameters specific to your environment. Use the following snippet as an example: Table 3.4. Heat parameters Parameter Value 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. 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: Verification Create a test secret: Retrieve the payload for the secret that you just created: 3.3.1. Load Balancing with Entrust nShield Connect You can now enable load sharing on Entrust nShield Connect HSMs by specifying an array of valid HSMs. When more than one HSMs are listed, load sharing is enabled. This feature is available in this release as a Technology Preview, and therefore is not fully supported by Red Hat. It should only be used for testing, and should not be deployed in a production environment. For more information about Technology Preview features, see Scope of Coverage Details . Procedure When configuring the name and ip parameters for your Entrust nShield Connect HSMs, specifying more than one will enable load sharing: 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 Add the following parameter to your deployment environment files: Change the labels on the MKEK and HMAC keys For example, if your labels are similar to these: You can change the labels by incrementing the values: Note Do not change the HMAC key type. 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.

Commands:
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
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
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 | +---------------+------------------------------------------------------------------------------------+
openstack secret get https://192.168.123.163/key-manager/v1/secrets/4cc5ffe0-eea2-449d-9e64-b664d574be53 --payload +---------+-------------+ | Field | Value | +---------+-------------+ | Payload | TestPayload | +---------+-------------+
sudo dnf install ansible-role-lunasa-hsm
parameter_defaults: BarbicanPkcs11CryptoMKEKLabel: "barbican_mkek_0" BarbicanPkcs11CryptoHMACLabel: "barbican_hmac_0" BarbicanPkcs11CryptoLogin: "USDPKCS_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:USDPASSWORD@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: "USDHSM_ADMIN_PASSWORD" partition: myPartition1 partition_serial: 123456789
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
parameter_defaults: VerifyGlanceSignatures: true SwiftEncryptionEnabled: 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_rfs_server_ip_address: 192.168.10.12 thales_hsm_config_location: hsm-C90E-02E0-D947 nShield_hsms: - name: hsm-name.example.com ip: 192.168.10.10 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
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
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 | +---------------+------------------------------------------------------------------------------------+
openstack secret get https://192.168.123.163/key-manager/v1/secrets/4cc5ffe0-eea2-449d-9e64-b664d574be53 --payload +---------+-------------+ | Field | Value | +---------+-------------+ | Payload | TestPayload | +---------+-------------+
parameter_defaults: . ThalesVars: . nshield_hsms: - name: hsm-name1.example.com ip: 192.168.10.10 - name: hsm-nam2.example.com ip: 192.168.10.11 .
BarbicanPkcs11CryptoRewrapKeys: true
BarbicanPkcs11CryptoMKEKLabel: 'barbican_mkek_10' BarbicanPkcs11CryptoHMACLabel: 'barbican_hmac_10'
BarbicanPkcs11CryptoMKEKLabel: 'barbican_mkek_11' BarbicanPkcs11CryptoHMACLabel: 'barbican_hmac_11'