2 Key Management with the barbican Service #
2.1 barbican Service Overview #
barbican is an OpenStack key management service offering secure storage, provisioning, and management of key data. The barbican service provides management of secrets, keys and certificates via multiple storage back-ends. The support for various back ends is provided via a plug-in mechanism, a Key Management Interoperability Protocol (KMIP) plug-in for a KMIP-compliant Hardware Secure Module (HSM) device. barbican supports symmetric and asymmetric key generation using various algorithms. cinder and nova will integrate with barbican for their encryption key generation and storage.
barbican has two types of core feature sets:
The barbican component, a Web Server Gateway Interface (WSGI) application that exposes a REST API for secrets/containers/orders.
barbican workers for asynchronous processing, which is used for various messaging-event-driven tasks related to certificate generation.
2.2 Key Features #
The major features of the barbican key management service are:
The ability to encrypt volumes/disks. In an OpenStack context, this means support for encrypting cinder volumes (volume encryption). cinder has its own key manager interface (KeyMgr) and can use
python-barbicanclient
as one of its implementations. By default in SUSE OpenStack Cloud 9, cinder uses barbican as its key manager when barbican is enabled. KeyMgr encrypts data in the virtualization host before writing data to the remote disk. There are three options available in SUSE OpenStack Cloud:Tenant-based encryption for block volume storage using barbican for KMS
barbican with KMIP and PKCS11 and external KMS (certified with Micro Focus ESKM)
3PAR StoreServ Data-At-Rest Encryption
Storage and retrieval of secrets (passwords)
The ability to define and manage access policies for key material
Administrative functionality, and the ability to control the lifecycle of key material
A well-defined auditing ability in OpenStack services for key access and lifecycle events
Key management as a service for PaaS application(s) deployed on an OpenStack cloud
The ability to scale key management effectively and make it highly available (able to handle failover)
Do not delete the certificate container associated with your load balancer listeners before deleting the load balancers themselves. If you delete the certificate first, future operations on your load balancers and failover will stop working.
2.3 Installation #
New installations of SUSE OpenStack Cloud 9:
For new installations, no changes are needed for barbican to be enabled. When installing your cloud, you should use the input models which already define the necessary barbican components. When using the pre-defined input model files that come with SUSE OpenStack Cloud 9, nothing else needs to be done in those files.
Generate a master key.
WarningDo not change your master key after deploying it to barbican.
If you decide to make configuration changes to your clean install of SUSE OpenStack Cloud 9, you will need to redeploy the barbican service. For details on available customization options, please see Chapter 3, Key Management Service Administration.
Master Key Configuration#
barbican currently supports databases and KMIP as its secret store back-ends. In OpenStack upstream additional back-ends are available, such as the PKCS11 and dogtag plug-ins, but they are not tested or supported by SUSE OpenStack Cloud.
In SUSE OpenStack Cloud, by default barbican is configured to use a database as a secret (keys) storage back-end. This back-end encrypts barbican-managed keys with a project level key (KEK/Key Encryption Key) before storing it in the database. Project-level keys are encrypted using a master key. As part of the initial barbican configuration, you must generate and configure this master key.
When barbican is used with simple_crypto_plugin
as
its secret store back-end, its master key needs to be defined
before initial deployment. If no key is
specified before deployment, the default master key is
used—this practice is discouraged.
Generate the master key using the provided python *generate_kek* script on the Cloud Lifecycle Manager node:
python ~/openstack/ardana/ansible/roles/KEYMGR-API/templates/generate_kek
The master key is generated at stdout from this command.
Set the master key in
~/openstack/my_cloud/config/barbican/barbican_deploy_config.yml
.If there is an existing
barbican_customer_master_key
value, replace it with the generated master key you just generated.Commit the change to the Git repository:
cd ~/openstack git add -A git commit -m "My config"
Run ready-deployment:
cd ~/openstack/ardana/ansible/ ansible-playbook -i hosts/localhost ready-deployment.yml
When the master key is set, continue with your cloud deployment.
Upgrade Master Key Configuration#
Check the master key.
If a master key is already defined, check
~/openstack/ardana/ansible/roles/barbican-common/vars/barbican_deploy_config.yml
forbarbican_customer_master_key
value. If the value does not have a prefix@ardana@
, it is not encrypted. It is highly recommended to encrypt this value.Encrypt the existing key during upgrade:
Set up the environment variable.
ARDANA_USER_PASSWORD_ENCRYPT_KEY
which contains the key used to encrypt barbican master key.
Before you run any playbooks, you need to export the encryption key in the following environment variable:
export ARDANA_USER_PASSWORD_ENCRYPT_KEY=<USER_ENCRYPTION_KEY>
python *roles/KEYMGR-API/templates/generate_kek <barbican_customer_master_key>
Master key is generated at stdout.
Set this master key in file
~/openstack/ardana/ansible/roles/barbican-common/vars/barbican_deploy_config.yml
Replace existing
barbican_customer_master_key
value with the master key you just generated.Commit the change in git repository.
cd ~/openstack/ardana/ansible/ ansible-playbook -i hosts/localhost ready-deployment.yml
When the master key is set, continue with cloud deployment.
Changing the master key during the upgrade process is discouraged. Changing the master key will result in a read error for existing secrets as they were encrypted using the previous master key.
For a barbican deployment with a database back-end, the master key needs to be generated and configured before barbican is deployed for the first time. Once the master key is set, it must not be modified.
Changing the master key can result in read errors for existing secrets as those secrets are stored in the database and are encrypted using the previous master key. Once a new master key is used, barbican will not be able to read those secrets. Also it will not be able to create new secrets within that project as the project key is encrypted using previous master key.
KMIP Plug-in Support#
barbican has a KMIP plug-in to store encryption keys (called secrets in barbican service terminology) in an HSM device using the KMIP protocol. This plug-in has been tested against Micro Focus ESKM with KMIP server. To enable support for it, barbican needs to be configured with the corresponding plug-in connection details, and client certificate information needs to be defined in its configuration. The ESKM KMIP server uses a client certificate to validate a KMIP client connection established by the barbican server. As part of that KMIP configuration, playbooks provide a mechanism to upload your client certs to nodes hosting the barbican API server.
KMIP deployment instructions can be found in Section 13.1, “Configuring KMIP and ESKM”.
Installation and deployment of the Micro Focus ESKM or any other HSM devices and dependent components is beyond the scope of this document. Please refer the relevant documentation for your choice of product. For example, you can get more information on Micro Focus ESKM and related Data Security and Encryption Products at https://software.microfocus.com/en-us/products/eskm-enterprise-secure-key-management/overview.
2.4 Auditing barbican Events #
The barbican service supports auditing and uses Chapter 15, Security Audit Logs to generate auditing data in Cloud Auditing Data Federation (CADF) format. The SUSE OpenStack Cloud input model has a mechanism to enable and disable auditing on a per-service basis. When barbican auditing is enabled, it writes audit messages to an audit log file that is separate from the barbican internal logging. The base location of audit log file is driven by common auditing configuration.
Enabling and Disabling Auditing#
The auditing of barbican events can be enabled and disabled through the barbican reconfigure playbook. As part of the configuration of barbican, its audit messages can be directed to a log or to a messaging queue. By default, messages are written to the barbican log file. Once an architecture-level decision is made with regards to the default consumer of audit events (either logging or messaging), the barbican service can be configured to use it as the default option when auditing is enabled.
Auditing can be disabled or enabled by following these steps on the Cloud Lifecycle Manager node.
Edit the file
~/openstack/my_cloud/definition/cloudConfig.yml
. All audit-related configuration is defined in the audit-settings section. You must use valid YAML syntax when specifying values.Any service (including barbican) that is listed under enabled-services or disabled-services will override the default setting. To enable auditing, make sure that the barbican service name is in the enabled-services list of the
audit-settings
section or is not present in disabled-services list when default: is set to enabled.The relevant section of
cloudConfig.yml
is shown below. Enabled-services are commented out.The
default: enabled
setting applies to all services. If you want to disable (or enable) a few, whichever is the opposite of the default global setting you used, you can do so in a disabled-services (or enabled-services) section below it. Here the enabled-services entry is commented out. You should only have either a default of enabled (or disabled) or a section of disabled (or enabled). There is no need to duplicate the setting.audit-settings: default: enabled #enabled-services: # - keystone # - barbican disabled-services: - nova - barbican - keystone - cinder - ceilometer - neutron
When you are satisfied with your settings, copy the files to
~/openstack/my_cloud/definition/
, and commit the changes in the git repository. For example, if you are using the Entry Scale KVM model, you would copy from~/openstack/examples/entry-scale-kvm
and commit.cp -r ~/openstack/examples/entry-scale-kvm/* ~/openstack/my_cloud/definition/ cd ~/openstack git add -A git commit -m "My config"
Run the configuration processor and ready-deployment:
cd ~/openstack/ardana/ansible/ ansible-playbook -i hosts/localhost config-processor-run.yml ansible-playbook -i hosts/localhost ready-deployment.yml
Run barbican-reconfigure:
cd ~/scratch/ansible/next/ardana/ansible ansible-playbook -i hosts/verb_hosts barbican-reconfigure.yml
2.5 barbican Key Management Service Bootstrap Data #
When the key management service is installed, some of the keystone-related initial data is bootstrapped as part of its initial deployment. The data added is primarily related to barbican user, roles, service and endpoint definitions, and barbican role assignments.
User, Roles, Service and Endpoint Definitions#
Type | Name or key-value pair | Purpose | Comments |
---|---|---|---|
keystone User Account |
barbican |
barbican user account associated with administrative privileges. |
Password is randomly generated and made available in the barbican
client environment setup script, |
keystone User Account |
barbican_service |
Service account used for keystone token validation by
|
Password is randomly generated and stored in barbican paste
configuration, |
keystone Role |
key-manager:creator |
barbican specific role with privilege to create, modify, list, and delete keys and certificates. |
This role has the same privileges defined for
|
keystone Role |
key-manager:admin |
barbican-specific role that has administrative privileges. Privileges include modifications (update and delete) in container's consumer, transport keys, certificate authorities (CA), assignment, and management of per-project CA. |
This role has the same privileges defined for |
keystone Role |
key-manager:observer |
barbican specific role which has privileges limited to read/list of keys, certificates. |
This role has the same privileges defined
for |
keystone Role |
key-manager:auditor |
barbican specific role which has privileges limited to reading metadata of keys, certificates. This role does not allow reading and listing of actual keys and certificates. |
This role has the same privileges defined for |
keystone Role |
key-manager:service-admin |
barbican specific role which has privilege to modify global preferred CA and modify default project quotas. |
This role has the same privileges defined
for |
keystone Service |
name: barbican type: key-manager |
barbican service definition. Service type is key-manager. | |
keystone Endpoint |
interface: internal region: region1 |
barbican internal endpoint. This is the load-balanced endpoint exposed for internal service usage. | |
keystone Endpoint |
interface: public region: region1 |
barbican public endpoint. This is the load-balanced endpoint exposed for external/public service usage. |
Role Assignments#
User name | Project name | Role name | Purpose |
---|---|---|---|
barbican | admin | key-manager:admin |
User is assigned barbican administration privileges on keystone-defined
|
barbican | admin | key-manager:service-admin |
User is assigned barbican service administration privileges on
keystone-defined |
barbican | admin | admin |
User assigned keystone defined administrative role on its
|
admin | admin | key-manager:admin |
keystone-defined |
admin | admin | key-manager:service-admin |
In lines of above role assignment, barbican specific service administrator role is assigned to allow global preferred CA and quotas modifications. |
barbican_service | services | service |
barbican service account is given |
2.6 Known issues and workarounds #
Make sure that in your Certificate Signing Request (CSR)
Common Name
matches thebarbican_kmip_username
value defined inroles/barbican-common/vars/barbican_deploy_config.yml
. Otherwise you may see an internal server error message in barbican for secret create request.barbican does not return a clear error message with regards to client certificate setup and its connectivity with KMIP server. During secret create request, a general "Internal Server Error" is returned when the certificate is invalid or missing any of necessary client certificate data (client certificate, key and CA root certificate).