Juju Charm - Barbican
Go to file
Alex Kavanagh 6d0248e9d9 Add barbican-hsm-plugin interface support
The barbican-hsm-plugin interface provides a mechanism for the Barbican
charm to communicate with an HSM plugin.  The plugin (from the Barbican
perspective) is provided as a PKCS#11 compliant library (.so) and so is
local to the Barbican installation.  Thus, the hsm-plugin charms are
subordinate to the Barbican charm and run on the same unit.

This change also provides two actions (generate-mkek and generate-hmac)
which are 'one-off' operations to initialise the HSM with the global
master keys.

Add a note to the README that the generate-mkek and generate-hmac
actions may only be done once as the HSM may reject overwriting the key.

Add Apache2.0 LICENSE and license headers to files
Removed redundant copyright file

Change the reference for the internal port to 9311 The barbican project
changed the INTERNAL port to the same as the PUBLIC port.

Add in seed_file and seed_length to template. These are needed for a
change in Barbican to support seeding the RNG in the HSM if required.
They are set to /dev/random and 32.

Fetch the barbican sources from a PPA (for bug: 1599550)

Remove the trusty support for Py3 from install hook
2016-07-12 12:35:51 +00:00
manual_testing move novarc to manual testing subdir 2016-05-18 14:44:44 +00:00
src Add barbican-hsm-plugin interface support 2016-07-12 12:35:51 +00:00
unit_tests Add barbican-hsm-plugin interface support 2016-07-12 12:35:51 +00:00
.gitignore Initial unit_tests added - NOT FUNCTIONAL at this stage 2016-05-19 18:00:23 +00:00
.testr.conf Initial unit_tests added - NOT FUNCTIONAL at this stage 2016-05-19 18:00:23 +00:00
LICENSE Add barbican-hsm-plugin interface support 2016-07-12 12:35:51 +00:00
Makefile Add barbican-hsm-plugin interface support 2016-07-12 12:35:51 +00:00
README.md Add barbican-hsm-plugin interface support 2016-07-12 12:35:51 +00:00
requirements.txt Get charm to build 2016-05-19 12:15:53 +00:00
setup.sh Render paste ini properly and other fixes 2015-12-11 13:43:03 +00:00
test-requirements.txt Add barbican-hsm-plugin interface support 2016-07-12 12:35:51 +00:00
tox.ini Add barbican-hsm-plugin interface support 2016-07-12 12:35:51 +00:00

Barbican Source Charm

This repository is for the reactive, layered, Barbican source charm. From the wiki 'Barbican is a REST API designed for the secure storage, provisioning and management of secrets such as passwords, encryption keys and X.509 Certificates. It is aimed at being useful for all environments, including large ephemeral Clouds.'

Plugins

The Barbican charm currently supports the following plugins:

Creating the primary MKEK and primary HMAC

Barbican (can use|uses) a Master Key Encryption Key (MKEK) scheme to wrap other keys so that in the course of issuing new encryption keys, it doesn't exhaust the storage capacity of an HSM.

See KMIP MKEK Model Plugin for more details.

Barbican itself can generate the MKEK and HMAC keys and store them in the associated HSM through the use of two actions 'generate-mkek' and 'generate-hmac'.

The names of the keys are stored in the configuration for the service as 'mkek-label' and 'hmac-label'. These default to 'primarymkek' and 'primaryhmac' respectively.

Note that these keys are not recoverable from the HSM. If the HSM has already been configured with these keys then these actions would overwrite the existing key. So only use them for the initial implementation or to change the MKEK and HMAC keys in the HSM.

Use of actions

For juju 1.x:

juju action do generate-mkek

For juju 2.x:

juju run-action generate-mkek

Note that, depending on the HSM, it may only be possible to do this ONCE as the HSM may reject setting up the keys more than once.

Developer Notes

The Barbican charm has to be able to set [crypto] and [xxx_plugin] sections in the barbican-api.conf file. This data comes via the barbican-hsm-plugin interface from a charm (probably a subordinate) that provides the interface.

On the barbican-hsm-interface the data is provided in the plugin_data() method of the interface (or if it is adapted) in the plugin_data property.

The theory of operation for the crypto plugin is that a local library that supports the PKCS#11 interface that Barbican can talk to locally.

Note(AJK): it is not clear yet how a clustered Barbican can be created with a single HSM backend. It's likely to be a separate piece of hardward with a local library that talks to it.

In order for Barbican to be configured for the example softhsm2 library, the configuration file needs to include the entries:

[crypto]
enabled_crypto_plugins = p11_crypto

[p11_crypto_plugin]
library_path = '/usr/lib/libCryptoki2_64.so'
login = 'catt'
mkek_label = 'primarymkek'
mkek_length = 32
hmac_label = 'primaryhmac' slot_id = <slot_id>

Note that the /var/lib/softhsm/tokens directory HAS to exist as otherwise the softhsm2-util command won't work.