openstack/barbican
Code Issues Proposed changes

Add plugin sub-folder and augment crypto plugin doc

Browse Source 
This CR creates a folder for plugins, to make way for documents pages
for each of the plugin types used in Barbican. The existing crypto
plugin page is moved to this new structure and revamped to add more
information on how Barbican core works with the plugin. The new plugin
section's index page has generic information on plugins (extracted
from the original plugin.rst) as well as defining what Barbican 'core'
is and how it interacts with plugins. Dependent CRs to add content
for the other plugin types will be coming soon.

Change-Id: Ia63c4e46cc7f01c334b41ec22ce8e9373b1a79da
This commit is contained in:
jfwood 2014-10-22 13:47:22 -05:00
parent 12bed77f89
commit a39d0a6c46
4 changed files with 141 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/index.rst
View File

@ -17,7 +17,7 @@ Getting Started
:maxdepth: 1
setup
plugin
plugin/index
Indices and tables

52
doc/source/plugin.rst
View File

@ -1,52 +0,0 @@
.. module:: barbican.plugin.crypto.crypto
========================================
Cryptographic Backend Plugin Development
========================================
Barbican currently defers cryptographic operations such as encryption and
decryption to pluggable backends. This gives flexibility to operators of
OpenStack clouds by allowing them to choose the right backend for their cloud.
While Barbican does provide a few implementations of cryptographic backend
plugins, some OpenStack operators may require a custom backend that performs
encryption, decryption and/or storage in a particular manner.
This guide describes how to develop a custom cryptographic backend plugin for
use by Barbican.
``plugin`` Module
=================
The ``barbican.crypto.plugin`` module contains the classes needed to implement
a custom plugin. These classes include the ``CryptoPluginBase`` abstract base
class which custom plugins should inherit from, as well as several Data
Transfer Object (DTO) classes used to transfer data between Barbican and the
plugin.
Data Transfer Objects
=====================
The DTO classes are used to wrap data that is passed from Barbican to the
plugin as well as data that is returned from the plugin back to Barbican.
They provide a level of isolation between the plugins and Barbican's interal
data models.
.. autoclass:: KEKMetaDTO
.. autoclass:: EncryptDTO
.. autoclass:: DecryptDTO
.. autoclass:: GenerateDTO
Plugin Base Class
=================
Custom Barbican backends should implement the abstract base class
``CryptoPluginBase``. Concrete implementations of this class should be exposed
to barbican using ``stevedore`` mechanisms explained later in this guide.
.. autoclass:: CryptoPluginBase
:members:

110
doc/source/plugin/crypto.rst Normal file
View File

@ -0,0 +1,110 @@
.. module:: barbican.plugin.crypto.crypto
==================================
Cryptographic Plugin Development
==================================
This guide describes how to develop a custom cryptographic plugin for use by
Barbican.
Barbican supports two storage modes for secrets. This document focuses on the
mode that stores encrypted secrets in Barbican's data store, utilizing a
cryptographic process or appliance (such as a hardware security module (HSM))
to perform the encryption/decryption.
The other secret storage mode is detailed in the 'secret store' section. Note
that cryptographic plugins are invoked from within the context of a 'secret
store' plugin via an adapter class, further described in the 'secret store'
section.
``crypto`` Module
=================
The ``barbican.plugin.crypto`` module contains the classes needed to implement
a custom plugin. These classes include the ``CryptoPluginBase``
abstract base class which custom plugins should inherit from, as well as
several Data Transfer Object (DTO) classes used to transfer data between
Barbican and the plugin.
Data Transfer Objects
=====================
The DTO classes are used to wrap data that is passed from Barbican to the
plugin as well as data that is returned from the plugin back to Barbican.
They provide a level of isolation between the plugins and Barbican's internal
data models.
.. autoclass:: KEKMetaDTO
.. autoclass:: EncryptDTO
.. autoclass:: DecryptDTO
.. autoclass:: GenerateDTO
.. autoclass:: GenerateDTO
Plugin Base Class
=================
Barbican cryptographic plugins should implement the abstract base class
``CryptoPluginBase``. Concrete implementations of this class should be exposed
to barbican using ``stevedore`` mechanisms explained in the configuration
portion of this guide.
.. autoclass:: CryptoPluginBase
:members:
Barbican Core Plugin Sequence
===============================
The sequence that Barbican invokes methods on ``CryptoPluginBase``
depends on the requested action as detailed next.
**For secret storage actions**, Barbican core calls the following methods:
1. ``supports()`` - Asks the plugin if it can support the
``barbican.plugin.crypto.crypto.PluginSupportTypes.ENCRYPT_DECRYPT``
operation type.
2. ``bind_kek_metadata()`` - Allows a plugin to bind an internal key encryption
key (KEK) to a project-ID, typically as a 'label' or reference to the actual
KEK stored within the cryptographic appliance. This KEK information is stored
into Barbican's data store on behalf of the plugin, and then provided back to
the plugin for subsequent calls.
3. ``encrypt()`` - Asks the plugin to perform encryption of an unencrypted secret
payload, utilizing the KEK bound to the project-ID above. Barbican core will
then persist the encrypted data returned from this method for later
retrieval. The name of the plugin used to perform this encryption is also
persisted into Barbican core, to ensure we decrypt this secret only with
this plugin.
**For secret decryptions and retrievals**, Barbican core will select the same
plugin as was used to store the secret, and then invoke its ``decrypt()``
method, providing both the persisted encrypted secret data as well as the same
project-ID KEK used to encrypt the secret above.
**For symmetric key generation**, Barbican core calls the following methods:
1. ``supports()`` - Asks the plugin if it can support the
``barbican.plugin.crypto.crypto.PluginSupportTypes.SYMMETRIC_KEY_GENERATION``
operation type.
2. ``bind_kek_metadata()`` - Same comments as for secret storage above.
3. ``generate_symmetric()`` - Asks the plugin to both generate a symmetric key, and
then encrypted it with the project-ID KEK. Barbican core persists this
newly generated and encrypted secret similar to secret storage above.
**For asymmetric key generation**, Barbican core calls the following methods:
1. ``supports()`` - Asks the plugin if it can support the
``barbican.plugin.crypto.crypto.PluginSupportTypes.ASYMMETRIC_KEY_GENERATION``
operation type.
2. ``bind_kek_metadata()`` - Same comments as for secret storage above.
3. ``generate_asymmetric()`` - Asks the plugin to generate and encrypt asymmetric
public and private key (and optional passphrase) information, which Barbican
core will persist as a container of separate encrypted secrets.

30
doc/source/plugin/index.rst Normal file
View File

@ -0,0 +1,30 @@
Plugin Developers Guide
=========================
This guide describes how to develop custom plugins for use by Barbican. While
Barbican provides useful plugin implementations, some OpenStack operators may
require customized implementations, perhaps to interact with a an existing
corporate database or service. This approach also gives flexibility to
operators of OpenStack clouds by allowing them to choose the right
implementation for their cloud.
Barbican's plugin architecture enables developers to create their own
implementations of features such as secret storage and generation, SSL
certificate generation, and event handling. The plugin pattern used defines an
abstract class, whose methods are invoked by Barbican logic (referred to as
Barbican 'core' in this guide) in a particular sequence. Typically plugins do
not interact with Barbican's data model directly, so Barbican core also handles
persisting any required information on the plugin's behalf.
In general, Barbican core will invoke a variation of the plugin's
``supports()`` method to determine if a requested action can be implemented by
the plugin. Once a supporting plugin is selected, Barbican core will invoke one
or more methods on the plugin to complete the action.
The links below provide further guidance on the various plugin types used by
Barbican, as well as configuration and deployment options.
.. toctree::
:maxdepth: 1
crypto