Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / Documentation / Security Guide / Key Management with the barbican Service
Applies to SUSE OpenStack Cloud 9

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)

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

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

  2. Set the master key in ~/openstack/my_cloud/config/barbican/barbican_deploy_config.yml.

  3. If there is an existing barbican_customer_master_key value, replace it with the generated master key you just generated.

  4. Commit the change to the Git repository:

    cd ~/openstack
    git add -A
    git commit -m "My config"
  5. Run ready-deployment:

    cd ~/openstack/ardana/ansible/
    ansible-playbook -i hosts/localhost ready-deployment.yml
  6. When the master key is set, continue with your cloud deployment.

Upgrade Master Key Configuration
  1. 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.

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

  3. 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
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
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
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
  1. 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.

  2. 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
  3. 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"
  4. 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
  5. 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
TypeName or key-value pairPurposeComments

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 nameProject nameRole namePurpose
barbicanadminkey-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.

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

barbicanadminadmin

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.

adminadminkey-manager:admin

keystone-defined admin user is given barbican related administrative privileges on keystone-defined admin project.

adminadminkey-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_serviceservicesservice

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

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

  2. 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).