Update Back End Documentation
Change-Id: I9c00245adf19e380ef31cc9da9aa66af3f697785
This commit is contained in:
Douglas Mendizábal
parent
f4b08f8d2e
commit
3c2a99604a
|
|
@ -8,12 +8,6 @@ encryption system such as an HSM (Hardware Security Module). In addition,
|
|||
the SQLite backend has known issues with thread-safety. This setup is purely
|
||||
to aid in development workflows.
|
||||
|
||||
.. warning::
|
||||
|
||||
The default key store implementation in Barbican **is not secure** in
|
||||
any way. **Do not use this development standalone mode to store sensitive
|
||||
information!**
|
||||
|
||||
Installing system dependencies
|
||||
------------------------------
|
||||
|
||||
|
|
@ -41,12 +35,12 @@ Setting up a virtual environment
|
|||
--------------------------------
|
||||
|
||||
We highly recommend using virtual environments for development. You can learn
|
||||
more about `Virtual Environments`_ in the Python Guide.
|
||||
more about `Virtual Environments`_ in The Python Tutorial.
|
||||
|
||||
If you installed tox in the previous step you should already have virtualenv
|
||||
installed as well.
|
||||
|
||||
.. _Virtual Environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/
|
||||
.. _Virtual Environments: https://docs.python.org/3/tutorial/venv.html
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -109,7 +103,7 @@ For more information on configuring Barbican with Keystone auth see the
|
|||
Building the Documentation
|
||||
--------------------------
|
||||
|
||||
You can build the html developer documentation using tox:
|
||||
You can build the html documentation using tox:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -123,4 +117,4 @@ You can run the unit test suite using tox:
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
tox -e py27
|
||||
tox -e py36
|
||||
|
|
|
|||
|
|
@ -1,10 +1,19 @@
|
|||
Welcome to Barbican's developer documentation!
|
||||
Welcome to the Barbican Project documentation!
|
||||
==============================================
|
||||
|
||||
Barbican is the OpenStack Key Manager service. It provides secure storage,
|
||||
provisioning and management of secret data. This includes keying material
|
||||
such as Symmetric Keys, Asymmetric Keys, Certificates and raw binary data.
|
||||
|
||||
API Guide
|
||||
==========
|
||||
|
||||
If you're trying to learn how to use barbican, you can start by reading about
|
||||
`Secrets in the Barbican API Guide <https://developer.openstack.org/api-guide/key-manager/secrets.html>`__.
|
||||
|
||||
Once you're comfortable working with secrets you can dig into the rest of the
|
||||
API.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
|
@ -13,16 +22,6 @@ such as Symmetric Keys, Asymmetric Keys, Certificates and raw binary data.
|
|||
install/index
|
||||
configuration/index
|
||||
contributor/index
|
||||
|
||||
API Reference
|
||||
=============
|
||||
|
||||
If you're trying to learn how to use barbican, you can start by reading about
|
||||
`Secrets in the Barbican API Guide <https://developer.openstack.org/api-guide/key-manager/secrets.html>`__.
|
||||
|
||||
Once you're comfortable working with secrets you can dig into the rest of the
|
||||
API.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
|
|
|
|||
|
|
@ -1,46 +1,57 @@
|
|||
.. _barbican_backend:
|
||||
|
||||
Secret Store Back-ends
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
Configure Secret Store Back-end
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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).
|
||||
store secrets in one or more secret stores. Secret stores can be
|
||||
software-based such as a software-only encryption mechanism, 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.
|
||||
Secret Stores implement both the encryption mechanisms as well as the storage
|
||||
of the encrypted secrets.
|
||||
|
||||
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`` :
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[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.
|
||||
This section compares all the plugins that are currently available and the
|
||||
security tradeoffs that need to be considered when deciding which pluings to
|
||||
use.
|
||||
|
||||
Simple Crypto Plugin
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This crypto plugin is configured by default in ``/etc/barbican/barbican.conf``. This plugin
|
||||
is completely insecure and is only suitable for development testing.
|
||||
This back end plugin implements encryption using only software. The encrypted
|
||||
secrets are stored in the Barbican database.
|
||||
|
||||
This crypto plugin is configured by default in ``/etc/barbican/barbican.conf``.
|
||||
|
||||
This plugin uses single symmetric key (kek - or 'key encryption key')
|
||||
- which is stored in plain text in the ``/etc/barbican/barbican.conf`` file to encrypt
|
||||
and decrypt all secrets.
|
||||
|
||||
+------------------+--------------------------------------------------------+
|
||||
| Security | ⚠ Master Key (KEK) stored in the configuration file |
|
||||
+------------------+--------------------------------------------------------+
|
||||
| Maturity | ✅ Tested on every patch |
|
||||
+------------------+--------------------------------------------------------+
|
||||
| Ease of Use | | ✅ Simple to deploy |
|
||||
| | | ❌ Key rotation is disruptive |
|
||||
| | | (all secrets must be re-encrypted) |
|
||||
+------------------+--------------------------------------------------------+
|
||||
| Scalability | | ✅ Storage can be scaled in SQL DB |
|
||||
| | | ✅ Failover/HA is simple, just run more barbican-api |
|
||||
| | instances |
|
||||
| | | ✅ High performance - Software crypto is fast |
|
||||
+------------------+--------------------------------------------------------+
|
||||
| Cost | ✅ Free (as in beer) |
|
||||
+------------------+--------------------------------------------------------+
|
||||
|
||||
.. warning::
|
||||
|
||||
This plugin stores its KEK in plain text in the configuration file,
|
||||
which will be present in any node running the `barbican-api` or
|
||||
`barbican-worker` services. Extreme care should be taken to prevent
|
||||
unauthrized access to these nodes. When using this plugin the KEK is the
|
||||
only thing protecting the secrets stored in the database.
|
||||
|
||||
The configuration for this plugin in ``/etc/barbican/barbican.conf`` is as follows:
|
||||
|
||||
.. code-block:: ini
|
||||
|
|
|
|||
Loading…
Reference in New Issue