barbican/install-guide/source/barbican-backend.rst

Secret Store Back-ends

The Key Manager service has a plugin architecture that allows the deployer to store secrets in one or more secret stores. Secret stores can be software-based such as a software token, or hardware devices such as a hardware security module (HSM).

This section describes the plugins that are currently available and how they might be configured.

Crypto Plugins

These types of plugins store secrets as encrypted blobs within the Barbican database. The plugin is invoked to encrypt the secret on secret storage, and decrypt the secret on secret retrieval.

To enable these plugins, add store_crypto to the list of enabled secret store plugins in the [secret_store] section of /etc/barbican/barbican.conf :

[secretstore]
namespace = barbican.secretstore.plugin
enabled_secretstore_plugins = store_crypto

There are two flavors of storage plugins currently available: the Simple Crypto plugin and the PKCS#11 crypto plugin.

Simple Crypto Plugin

This crypto plugin is configured by default in barbican.conf. This plugin is completely insecure and is only suitable for development testing.

Warning

THIS PLUGIN IS NOT SUITABLE FOR PRODUCTION DEPLOYMENTS.

This plugin uses single symmetric key (kek - or 'key encryption key') - which is stored in plain text in the barbican.conf file to encrypt and decrypt all secrets.

The configuration for this plugin in barbican.conf is as follows:

# ================= Secret Store Plugin ===================
[secretstore]
..
enabled_secretstore_plugins = store_crypto

# ================= Crypto plugin ===================
[crypto]
..
enabled_crypto_plugins = simple_crypto

[simple_crypto_plugin]
# the kek should be a 32-byte value which is base64 encoded
kek = 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY='

PKCS#11 Crypto Plugin

This crypto plugin can be used to interface with a Hardware Security Module (HSM) using the PKCS#11 protocol.

Secrets are encrypted (and decrypted on retrieval) by a project specific Key Encryption Key (KEK), which resides in the HSM.

The configuration for this plugin in barbican.conf with settings shown for use with a SafeNet HSM is as follows:

# ================= Secret Store Plugin ===================
[secretstore]
..
enabled_secretstore_plugins = store_crypto

[p11_crypto_plugin]
# Path to vendor PKCS11 library
library_path = '/usr/lib/libCryptoki2_64.so'
# Password to login to PKCS11 session
login = 'mypassword'
# Label to identify master KEK in the HSM (must not be the same as HMAC label)
mkek_label = 'an_mkek'
# Length in bytes of master KEK
mkek_length = 32
# Label to identify HMAC key in the HSM (must not be the same as MKEK label)
hmac_label = 'my_hmac_label'
# HSM Slot id (Should correspond to a configured PKCS11 slot). Default: 1
# slot_id = 1
# Enable Read/Write session with the HSM?
# rw_session = True
# Length of Project KEKs to create
# pkek_length = 32
# How long to cache unwrapped Project KEKs
# pkek_cache_ttl = 900
# Max number of items in pkek cache
# pkek_cache_limit = 100

KMIP Plugin

This secret store plugin is used to communicate with a KMIP device. The secret is securely stored in the KMIP device directly, rather than in the Barbican database. The Barbican database maintains a reference to the secret's location for later retrieval.

The plugin can be configured to authenticate to the KMIP device using either a username and password, or using a client certificate.

The configuration for this plugin in barbican.conf is as follows:

[secretstore]
..
enabled_secretstore_plugins = kmip_crypto

[kmip_plugin]
username = 'admin'
password = 'password'
host = localhost
port = 5696
keyfile = '/path/to/certs/cert.key'
certfile = '/path/to/certs/cert.crt'
ca_certs = '/path/to/certs/LocalCA.crt'

Dogtag Plugin

Dogtag is the upstream project corresponding to the Red Hat Certificate System. a robust, full-featured PKI solution that contains a Certificate Manager (CA) and a Key Recovery Authority (KRA) which is used to securely store secrets.

The KRA stores secrets as encrypted blobs in its internal database, with the master encryption keys being stored either in a software-based NSS security database, or in a Hardware Security Module (HSM).

Note that the software-based NSS database configuration provides a secure option for those deployments that do not require or cannot afford an HSM. This is the only current plugin to provide this option.

The KRA communicates with HSMs using PKCS#11. For a list of certified HSMs, see the latest release notes. Dogtag and the KRA meet all the relevant Common Criteria and FIPS specifications.

The KRA is a component of FreeIPA. Therefore, it is possible to configure the plugin with a FreeIPA server. More detailed instructions on how to set up Barbican with FreeIPA are provided here.

The plugin communicates with the KRA using a client certificate for a trusted KRA agent. That certificate is stored in an NSS database as well as a PEM file as seen in the configuration below.

The configuration for this plugin in barbican.conf is as follows:

[secretstore]
..
enabled_secretstore_plugins = dogtag_crypto

[dogtag_plugin]
pem_path = '/etc/barbican/kra_admin_cert.pem'
dogtag_host = localhost
dogtag_port = 8443
nss_db_path = '/etc/barbican/alias'
nss_password = 'password123'