OpenStack Barbican
This guide is tailored for security administrators looking to integrate OpenStack Barbican with a Thales Luna HSM or Luna Cloud HSM. Barbican serves as a robust platform for securely storing and managing sensitive assets, such as passwords and encryption keys. At the heart of its security lies the Master Key Encryption Key (MKEK), a critical component that safeguards other essential keys. The MKEK is securely housed within the trusted hardware of the Thales HSM, ensuring unparalleled protection.
This document provides step-by-step instructions for configuring Barbican to leverage the HSM for encryption and decryption tasks, reinforcing the security of sensitive data. By implementing this integration, organizations gain the following advantages:
-
Secure generation, storage, and protection of the identity signing private keys using either FIPS 140-2 or FIPS 140-3 Level 3 validated hardware.
-
Full life cycle management of the keys to ensure their integrity and reliability throughout their usage.
-
Maintenance of a comprehensive HSM audit trail for transparency and accountability in key operations. It's important to note that Luna Cloud HSM service does not have access to this secure audit trail.
-
Significant performance enhancements by offloading cryptographic operations from application servers.
Supported Platforms
This integration is supported in FIPS mode for Luna HSM with firmware version 7.4.x or earlier, up to the OpenStack Barbican Zed release. For Luna HSM firmware version 7.7.x or later, only releases after OpenStack Barbican Zed are supported in FIPS mode. For additional details, refer to the following link: OpenStack Barbican Fix.
Prerequisites
The prerequisites for this integration are:
Set up Luna HSM
As the first step to accomplish this integration, you need to set up either On-Premise Luna HSM or Luna Cloud HSM.
Set up On-Premise Luna HSM
Follow these steps to set up your on-premise Luna HSM:
Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.
Create a partition that will be later on used by OpenStack Barbican.
Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.
Initialize Crypto Officer and Crypto User roles for the registered partition.
Run the following command to verify that the partition has been successfully registered and configured:
/usr/safenet/lunaclient/bin/lunacm
Upon successful execution, you should observe an output similar to the example provided below:
lunacm.exe (64-bit) v10.7.2-16. Copyright (c) 2024 Thales Group. All rights reserved. Available HSMs: Slot Id -> 0 Label -> TPA01 Serial Number -> 1312109862218 Model -> LunaSA 7.7.1 Firmware Version -> 7.7.1 Bootloader Version -> 1.1.2 Configuration -> Luna User Partition With SO (PW) Key Export With Cloning Mode Slot Description -> Net Token Slot FM HW Status -> Non-FM Current Slot Id: 0
For PED-authenticated HSMs, enable Partition Policies 22 and 23 to support activation and auto-activation.
Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.
Manage user access to the HSM
By default, access to the HSM device is limited to the root user. If you need to grant access to the HSM for specific non-root users, you can achieve this by including them in the hsmusers group. The hsmusers group is automatically generated during the client software installation process and remains intact even if you uninstall the client software. This design enables you to update your client software without losing your hsmusers group settings.
Add users to the hsmusers group
If you wish to permit non-root users or applications to interact with the HSM device, you must assign these users to the hsmusers group. Make sure that the users you intend to add to the hsmusers group are already established on the client workstation. Only users added to the hsmusers group will be granted access to the HSM device. Follow these steps to add a user to the hsmusers group:
Ensure that you possess sudo privileges on the client workstation.
Add a user to the hsmusers group using the command:
sudo gpasswd --add <username> hsmusers
Replace username
with the actual username you want to include in the hsmusers group.
Remove users from the hsmusers group
If you need to withdraw a user's authorization to access the HSM device, you can remove them from the hsmusers group. Carry out the following steps to remove a user from the hsmusers group:
Confirm that you hold sudo privileges on the client workstation.
Eliminate a user from the hsmusers group using the command:
sudo gpasswd --add <username> hsmusers
Replace username
with the specific username you want to exclude from the hsmusers group. To observe the changes, you will need to log in again.
Any user you remove will retain access to the HSM device until the client workstation is rebooted.
Set up Luna HSM High-Availability Group
Refer to Luna HSM documentation for HA steps and details regarding configuring and setting up two or more HSM boxes on host systems. You must enable the HAOnly
setting in HA for failover to work so that if the primary goes down due to any reason, all calls get automatically routed to the secondary until the primary recovers and starts up.
Set up Luna Cloud HSM
Follow these steps to set up your Luna Cloud HSM:
Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means
This integration has been certified on the RHEL platform.
Extract the .zip file into a directory on your client workstation.
Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.
tar -xvf cvclient-min.tar
Run the setenv script to create a new configuration file containing information required by the Luna Cloud HSM service.
source ./setenv
To add the configuration to an already installed UC client, use the –addcloudhsm
option when running the setenv script.
Run the LunaCM utility and verify that the Cloud HSM service is listed.
If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.
Set up OpenStack Barbican
Integrating OpenStack Barbican with a Thales HSM requires a foundational understanding of Barbican’s functionality. Follow these steps to prepare for the integration:
Review the official OpenStack Barbican documentation to understand installation requirements, setup procedures, and how Barbican manages sensitive data.
Install OpenStack Barbican on the designated machine where it will be integrated with the Thales HSM, ensuring all prerequisites from the documentation are fulfilled.
Configure OpenStack Barbican with Thales Luna HSM or Luna Cloud HSM
To set up OpenStack Barbican for integration with Thales Luna HSM or Luna Cloud HSM, follow these steps:
Run the following command to add the barbican
user to the hsmusers
group:
gpasswd --add barbican hsmusers
Skip this step if you are using the Luna Cloud HSM service client.
Use the command below to configure the Barbican environment:
source keystonerc_admin
Open the Barbican configuration file located at /etc/barbican/barbican.conf
and apply the changes based on the OpenStack Barbican version you are using.
For Versions After OpenStack Barbican Zed
Add the following configurations under the relevant sections:
Enter hmac_key_type
and hmac_keygen_mechanism
details only when generating a new HMAC key. If you are upgrading from a previous version and already have an HMAC key, these flags are not required.
[secretstore] enable_multiple_secret_stores = True stores_lookup_suffix = luna namespace = barbican.secretstore.plugin [secretstore:luna] secret_store_plugin = store_crypto crypto_plugin = p11_crypto global_default = True [p11_crypto_plugin] library_path = '<path_to_cryptoki_library>' slot_id = <partition_slot_id> login = '<partition_password>' encryption_mechanism = CKM_AES_GCM # Options: CKM_AES_CBC or CKM_AES_GCM mkek_label = '<mkek_label>' hmac_label = '<hmac_label>' hmac_key_type = CKK_GENERIC_SECRET hmac_keygen_mechanism = CKM_GENERIC_SECRET_KEY_GEN hmac_mechanism = CKM_SHA256_HMAC key_wrap_mechanism = CKM_AES_KEY_WRAP_KWP aes_gcm_generate_iv = False # Required only if CKM_AES_GCM is used.
For Versions Till OpenStack Barbican Zed
Add the following configurations under the relevant sections:
[secretstore] namespace = barbican.secretstore.plugin enabled_secretstore_plugins = store_crypto [crypto] enabled_crypto_plugins = p11_crypto [p11_crypto_plugin] library_path = '<path_to_cryptoki_library>' login = '<partition_password>' mkek_label = '<mkek_label>' mkek_length = 32 hmac_label = '<hmac_label>' slot_id = <partition_slot_id>
Ensure that the barbican.conf
file contains accurate information about the Luna HSM and the generated key materials.
Generate the MKEK on the Luna HSM partition or the Luna Cloud HSM service. Use the following command:
If you are upgrading from a previous version and the MKEK already exists on the HSM, skip this step.
barbican-manage hsm gen_mkek --library-path '<path_to_cryptoki_library>' --passphrase '<partition_password>' --slot-id <partition_slot_id> --label '<mkek_label>' --length 32
Example:
barbican-manage hsm gen_mkek --library-path '/usr/safenet/lunaclient/lib/libCryptoki2_64.so' --passphrase 'userpin1' --slot-id 0 --label 'luna_mkek_1' --length 32
The HMAC key is generated on the registered HSM partition. Run the following command:
If you are upgrading from a previous version and the HMAC key already exists on the HSM, skip this step.
barbican-manage hsm gen_hmac --library-path '<path_to_cryptoki_library>' --passphrase '<partition_password>' --slot-id <partition_slot_id> --label '<hmac_label>' --length 32
Example:
# barbican-manage hsm gen_hmac --library-path '/usr/safenet/lunaclient/lib/libCryptoki2_64.so' --passphrase 'userpin1' --slot-id 0 --label 'luna_hmac_1' --length 32
After configuration, restart the Barbican API and HTTP services:
systemctl restart openstack-barbican-api.service
systemctl restart httpd.service
To store a secret in Barbican, use the following command:
openstack secret store --name "<secret-name>" --payload '<secret-value>'
Example:
openstack secret store --name "FirstSecret" --payload 'Fir$t1t0te$t'
If this command fails with the error CKR_INVALID_ATTRIBUTE
, locate the pkcs11.py
file (e.g., /usr/lib/python2.7/site-packages/barbican/plugin/crypto/pkcs11.py
) and set CKA_SENSITIVE = True
.
Retrieve the stored secret (excluding its payload) using this command:
openstack secret get "<secret-href>"
Example:
openstack secret get "http://10.164.77.249:9311/v1/secrets/ed0ff260-1c0c-41b7-95e6-dd8c3405aade"
To fetch the original secret value, use the following command:
openstack secret get "<secret-href>" --payload
Example:
openstack secret get "http://10.164.77.249:9311/v1/secrets/ed0ff260-1c0c-41b7-95e6-dd8c3405aade" --payload
When you run this command, the decrypted secret payload will be displayed in the response, allowing you to verify the stored data.
Troubleshooting
Problem:
Secret encryption in Barbican is unsuccessful, and the following error appears in the logs:
ERROR barbican.api.controllers barbican.common.exception.P11CryptoPluginException: HSM returned response code: 0x70 CKR_MECHANISM_INVALID.
Cause:
-
This issue can occur if you are using Luna HSM firmware version 7.7.x in FIPS mode with a Barbican version older than any release after Barbican Zed.
-
Alternatively, even if you are running a Barbican version after Zed, the issue might occur if the Barbican installation lacks fixes merged later. This could happen if Barbican was installed from an OS repository built before the fix mentioned in the commit.
Solution:
Follow the steps below to resolve this issue:
Clone the Barbican GitHub repository containing the merged fix:
git clone https://github.com/openstack/barbican.git
Create a backup of the currently installed Barbican directory:
mv /usr/lib/python3.9/site-packages/barbican /usr/lib/python3.9/site-packages/barbican.bkp
Copy the downloaded Barbican directory to replace the existing one:
cp -r barbican/barbican /usr/lib/python3.9/site-packages/
Restart the Barbican API and HTTP services to apply the changes:
systemctl restart openstack-barbican-api.service
systemctl restart httpd.service
Create an encrypted secret to verify the issue is resolved:
openstack secret store --name "secret-fix" --payload 'Te$tthef1x'
By completing these steps, the CKR_MECHANISM_INVALID error should no longer occur during secret encryption.