SUSE OpenStack Cloud 9 | Security Guide | 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)

Warning

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.
Warning
Do 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 for barbican_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:
1. Set up the environment variable.
```
ARDANA_USER_PASSWORD_ENCRYPT_KEY
```
  which contains the key used to encrypt barbican master key.
2. Before you run any playbooks, you need to export the encryption key in the following environment variable:
  1. ```
  export ARDANA_USER_PASSWORD_ENCRYPT_KEY=<USER_ENCRYPTION_KEY>
```
2. ```
python
*roles/KEYMGR-API/templates/generate_kek <barbican_customer_master_key>
```
  3. Master key is generated at stdout.
  4. Set this master key in file
```
~/openstack/ardana/ansible/roles/barbican-common/vars/barbican_deploy_config.yml
```
  5. Replace existing barbican_customer_master_key value with the master key you just generated.
  6. Commit the change in git repository.
  7. ```
  cd ~/openstack/ardana/ansible/
  ansible-playbook -i hosts/localhost ready-deployment.yml
```
8. 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.

Note

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.

Note

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”.

Note

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.

Procedure 2.1: Enabling or Disabling Auditing #

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, `barbican.osrc`, on the Cloud Lifecycle Manager node.
keystone User Account	barbican_service	Service account used for keystone token validation by `barbican` service.	Password is randomly generated and stored in barbican paste configuration, `barbican-api-paste.ini`.
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 `creator` role in upstream barbican. Referenced in the service policy config file, `policy.json`.
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 `admin` role in upstream barbican. Referenced in the service policy config file, `policy.json`.
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 `observer` role in upstream barbican. Referenced in the service policy config file, `policy.json`.
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 `auditor` role in upstream barbican. Referenced in the service policy config file, `policy.json`.
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 `key-manager:service-admin` role in upstream barbican. Referenced in the service policy config file, `policy.json`.
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 `admin` project. This allows the user to manage barbican resources associated with that project using the barbican CLI setup.
barbican	admin	key-manager:service-admin	User is assigned barbican service administration privileges on keystone-defined `admin` project. This role and the one above allows full barbican-related administration capabilities.
barbican	admin	admin	User assigned keystone defined administrative role on its `admin` project. This way customer can continue to use barbican CLI and OpenStack CLI without need to switch when testing or verifying data.
admin	admin	key-manager:admin	keystone-defined `admin` user is given barbican related administrative privileges on keystone-defined `admin` project.
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 `service` role on `services` project for token validation. API server uses this for creating scoped service token and then includes it as `X-Service-Token` when requesting customer/client token validation from keystone.

2.6 Known issues and workarounds #

Make sure that in your Certificate Signing Request (CSR) Common Name matches the barbican_kmip_username value defined in roles/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).

2 Key Management with the barbican Service #

2.1 barbican Service Overview #

2.2 Key Features #

2.3 Installation #

Master Key Configuration#

Upgrade Master Key Configuration#

KMIP Plug-in Support#

2.4 Auditing barbican Events #

Enabling and Disabling Auditing#

2.5 barbican Key Management Service Bootstrap Data #

User, Roles, Service and Endpoint Definitions#

Role Assignments#

2.6 Known issues and workarounds #