Merge "Add Key Management Chapter"

This commit is contained in:
Jenkins 2017-10-05 17:59:08 +00:00 committed by Gerrit Code Review
commit 94ba7e3343
9 changed files with 493 additions and 0 deletions

View File

@ -45,6 +45,7 @@ Contents
shared-file-systems.rst
networking.rst
object-storage.rst
secrets-management.rst
messaging.rst
data-processing.rst
databases.rst

View File

@ -0,0 +1,33 @@
==================
Secrets Management
==================
Operators protect sensitive information in cloud deployments by using various
applications of cryptography. For example, encrypting data at rest or signing
an image to prove that it has not been tampered with. In all cases, these
cryptographic capabilities require some sort of *key material* in order to
operate.
Secrets Management describes a group of technologies that are designed to
protect key materials within a software system. Traditionally, key management
involves deployment of `Hardware Security Modules (HSM) <https://en.wikipedia.org/wiki/Hardware_security_module/>`_.
These devices have been physically hardened against tampering.
As technology has advanced the number of secret things that need to be
protected has increased beyond key materials to include certificate pairs, API
keys, system passwords, signing keys and so on. This increase has created a
need for a more scalable approach to key management, and resulted in the
creation of a number of software services that provide scalable dynamic
key management. This chapter describes the services that exist today
and focus on those that are able to be integrated into OpenStack clouds.
.. toctree::
:maxdepth: 2
secrets-management/summary-of-technologies.rst
secrets-management/related-projects.rst
secrets-management/secrets-management-use-cases.rst
secrets-management/barbican.rst
secrets-management/castellan.rst
secrets-management/faq.rst
secrets-management/checklist.rst

View File

@ -0,0 +1,117 @@
========
Barbican
========
Overview
--------
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.
Barbican is integrated with several OpenStack features, either directly
or as a back end of `Castellan <https://wiki.openstack.org/wiki/Castellan>`_.
Barbican is often used as a key management system to enable use cases such as
Image signature verification, Volume encryption. These use cases are outlined
in the :doc:`secrets-management-use-cases`
Barbican Role Based Access Control
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
pending
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 discusses the security posture
of each one. Plugins are enabled and configured with settings in the
``/etc/barbican/barbican.conf`` configuration file.
There are two types of plugins: crypto plugins and secret store plugins.
Crypto plugins
--------------
Crypto 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. There are two
flavors of storage plugins currently available: the Simple Crypto plugin
and the PKCS#11 crypto plugin.
Simple crypto plugin
--------------------
The simple crypto plugin is configured by default in ``barbican.conf``.
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. This plugin is considered a less secure option
and is only suitable for development and testing as the master key is stored
within a config file in plain text, and is therefore not recommended
for use in production deployments.
PKCS#11 crypto plugin
---------------------
The PKCS#11 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. Since a different KEK is used for each
project, and since the KEKs are stored inside an HSM (instead of in
plaintext in the configuration file) the PKCS#11 plugin is much more
secure than the simple crypto plugin. It is the most popular back end
amongst Barbican deployments.
Secret store plugins
--------------------
Secret store plugins interface with secure storage systems to store the
secrets within those systems. There are two types of secret store
plugins: the KMIP plugin and the Dogtag plugin.
KMIP plugin
-----------
The `Key Management Interoperability Protocol (KMIP) <https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=kmip>`_
secret store plugin is used to communicate with a KMIP-enabled device, such as
a Hardware Security Module (HSM). The secret is securely stored in the
KMIP-enabled 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-enabled device using either a username and password, or using a client
certificate. This information is stored in the Barbican configuration file.
Dogtag plugin
-------------
The Dogtag secret store plugin is used to communicate with `Dogtag <http://pki.fedoraproject.org/wiki/PKI_Main_Page>`_.
Dogtag is the upstream project corresponding to the Red Hat Certificate
System, a Common Criteria/FIPS certified PKI solution that contains a
Certificate Manager (CA) and a Key Recovery Authority (KRA) which is use
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). The software-based NSS database configuration
provides a secure option for deployments that do not wish to use a HSM.
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 `in the following blog post <https://vakwetu.wordpress.com/2015/11/30/barbican-and-dogtagipa/>`_.
Threat analysis
~~~~~~~~~~~~~~~
The Barbican team worked with the OpenStack Security Project to perform a
security review of a best practise Barbican deployment. The objective of
the security review is to identify weaknesses and defects in the design
and architecture of services, and propose controls or fixes to resolve
these issues.
The Barbican threat analysis identified eight security findings and two
recommendations to improve the security of a barbican deployment. These
results can be reviewed in the `security analysis repo <https://github.com/openstack/security-analysis/tree/master/doc/source/artifacts/barbican/newton>`_., along with the
Barbican architecture diagram and architecture description page.

View File

@ -0,0 +1,10 @@
=========
Castellan
=========
Overview
--------
Castellan is a generic Key Manager interface developed by the Barbican team. It
enables projects to use a configurable key manager that can be deployment
specific.

View File

@ -0,0 +1,120 @@
.. _key_mgr_checklist:
=========
Checklist
=========
.. _check_key_mgr_01:
Check-Key-Manager-01: Is the ownership of config files set to root/barbican?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuration files contain critical parameters and information required
for smooth functioning of the component. If an unprivileged user, either
intentionally or accidentally, modifies or deletes any of the parameters
or the file itself then it would cause severe availability issues
resulting in a denial of service to the other end users. User ownership
of such critical configuration files must be set to root and group
ownership must be set to barbican.
Run the following commands:
.. code:: console
$ stat -L -c "%U %G" /etc/barbican/barbican.conf | egrep "root barbican"
$ stat -L -c "%U %G" /etc/barbican/barbican-api-paste.ini | egrep "root barbican"
$ stat -L -c "%U %G" /etc/barbican/policy.json | egrep "root barbican"
**Pass:** If user and group ownership of all these config files is set
to root and barbican respectively. The above commands show output of
root / barbican.
**Fail:** If the above commands do not return any output, it is possible
that the user and group ownership may have been set to any user other
than root or any group other than barbican.
.. _check_key_mgr_02:
Check-Key-Manager-02: Are strict permissions set for configuration files?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Similar to the previous check, we recommended to set strict access
permissions for such configuration files.
Run the following commands:
.. code:: console
$ stat -L -c "%a" /etc/barbican/barbican.conf
$ stat -L -c "%a" /etc/barbican/barbican-api-paste.ini
$ stat -L -c "%a" /etc/barbican/policy.json
**Pass:** If permissions are set to 640 or stricter. The permissions of
640 translates into owner r/w, group r, and no rights to others, for
example "u=rw,g=r,o=".
.. note::
With :ref:`check_key_mgr_01` and permissions set to 640, root
has read/write access and barbican has read access to these
configuration files. The access rights can also be validated using the
following command. This command will only be available on your system
if it supports ACLs.
.. code:: console
$ getfacl --tabular -a /etc/barbican/barbican.conf
getfacl: Removing leading '/' from absolute path names
# file: etc/barbican/barbican.conf
USER root rw-
GROUP barbican r--
mask r--
other ---
**Fail:** If permissions are set to at least 640.
**Fail:** If permissions are set greater then 640.
.. _check_key_mgr_03:
Check-Key-Manager-03: Is OpenStack Identity used for authentication?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OpenStack supports various authentication strategies like ``noauth`` and
``keystone``. If the ``noauth`` strategy is used then the users can
interact with OpenStack services without any authentication. This could
be a potential risk since an attacker might gain unauthorized access to
the OpenStack components. We strongly recommend that all services must
be authenticated with keystone using their service accounts.
**Pass:** If the parameter ``authtoken`` is listed under the
``pipeline:barbican_api`` section in ``barbican-api-paste.ini``.
**Fail:** If the parameter ``authtoken`` is missing under the
``pipeline:barbican_api`` section in ``barbican-api-paste.ini``.
.. _check_key_mgr_04:
Check-Key-Manager-04: Is TLS enabled for authentication?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OpenStack components communicate with each other using various protocols
and communication might involve sensitive or confidential data. An
attacker may try to eavesdrop on the channel in order to get access to
sensitive information. Therefore all components must communicate with
each other using a secured communication protocol.
**Pass:** If value of parameter ``auth_protocol`` under
``[keystone_authtoken]`` section in ``barbican.conf`` is set to
``https``, or if value of parameter ``identity_uri`` under
``[keystone_authtoken]`` section in ``barbican.conf`` is set to
Identity API endpoint starting with ``https://`` and value of parameter
``insecure`` under the same ``[keystone_authtoken]`` section in the same
``barbican.conf`` is set to ``False``.
**Fail:** If value of parameter ``auth_protocol`` under
``[keystone_authtoken]`` section in ``barbican.conf`` is set to
``http``, or if value of parameter ``identity_uri`` under
``[keystone_authtoken]`` section in ``barbican.conf`` is not set
to Identity API endpoint starting with ``https://`` or value of parameter
``insecure`` under the same ``[keystone_authtoken]`` section in the same
``barbican.conf`` is set to ``True``.

View File

@ -0,0 +1,47 @@
==========================
Frequently Asked Questions
==========================
1. What is the recommended way to securely store secrets in OpenStack?
The recommended way to securely store and manage secrets in OpenStack
is to use Barbican.
2. Why should I use Barbican?
Barbican is an OpenStack service that is multi-tenant aware and that
uses Keystone tokens for authentication. This means that access to secrets is
controlled via OpenStack policies for tenants and RBAC roles.
Barbican has multiple pluggable back-ends which can communicate with
software and hardware based security modules using PKCS#11 or KMIP.
3. What if I don't want to use Barbican?
In an Openstack context, there are two types of secrets that need to
be managed - those that require a keystone token for access, and those that do
not.
An example of those secrets that require keystone authentication are
passwords and keys owned by specific projects. These include, for instance,
encryption keys for a project's encrypted cinder volumes or signing keys for a
project's glance images.
Examples of secrets that does not require a keystone token to access
are passwords for service users in service configuration files, or
encryption keys that do not belong to any particular project.
Secrets that require a keystone token should be stored using Barbican.
Secrets that do not require keystone authentication can be stored in any secret
store that implements the simple key storage API that is exposed through
Castellan. This also includes Barbican.
4. How can I use Vault, Keywhiz, Custodia etc ...?
The key manager of your choice can be used with Openstack if Castellan
plugin has been written for that key manager. Once that plugin
has been written, it is relatively trivial to use the plugin either directly or
behind Barbican.
Currently, Vault and Custodia plugins are being developed for the Queens cycle.

View File

@ -0,0 +1,33 @@
==========================
Related Openstack Projects
==========================
`Castellan <https://docs.openstack.org/castellan/latest/>`_ is a library that
provides a simple common interface to store, generate and retrieve secrets. It
is used by most Openstack services for secret management. As a library,
Castellan does not provide a secret store in and of itself. Rather, a back-end
implementation is required to be deployed.
Note that Castellan does not provide any authentication. It simply passes
through the authentication credentials (a Keystone token, for example) to the
back-end.
`Barbican <https://docs.openstack.org/barbican/latest/>`_ is an OpenStack service that provides a back-end for Castellan.
Barbican expects and authenticates a keystone authentication token to identify
the user and project accessing or storing a secret. It then applies policy to
determine if access is permitted. It also provides a number of additional
useful features to improve secret management including quotas, per-secret ACLs,
tracking of secret consumers and grouping of secrets in secret containers.
Octavia, for example, integrates directly with Barbican (instead of Castellan)
to take advantage of some of these features.
Barbican has a number of back-end plugins that can be used to securely store
secrets in local databases or in HSMs.
Currently, Barbican is the only available back-end for Castellan. There are,
however, several back-ends that are being developed, including KMIP, Dogtag,
Hashicorp Vault and Custodia. For those deployers who do not wish to deploy
Barbican and have relatively simple key management needs, using one of these
back-ends could be a viable alternative. What would be lacking though is
multi-tenancy and tenant-policy enforcement when retrieving the secrets, as
well as any of the extra features mentioned above.

View File

@ -0,0 +1,111 @@
=========
Use Cases
=========
Image signature verification
----------------------------
Verification of image signatures assures that an image is not replaced or
changed since the time of original upload. The image signature verification
feature uses Castellan as its key manager for storing cryptographic signatures.
An image signature and certificate UUID is uploaded along with the image to the
Image (glance) service. Glance verifies the signature after retrieving the
certificate from the key manager. When the image is booted, the Compute
service (nova) verifys the signature after it retrieves the certificate from
the key manager.
For more details, see the `Trusted Images documentation
<https://docs.openstack.org/security-guide/instance-management/security-services-for-instances.html#trusted-images/>`_.
Volume encryption
-----------------
The volume encryption feature provides encryption of data-at-rest using
Castellan. When a user creates an encrypted volume type, and creates a
volume using that type, the Block Storage (cinder) service requests the key
manager to create a key to be associated with that volume. When the volume is
attached to an instance, nova retrieves the key.
For more details, see the `Data Encryption section <https://docs.openstack.org/security-guide/tenant-data/data-encryption.html>`_.
and `Volume encryption <https://docs.openstack.org/ocata/config-reference/block-storage/volume-encryption.html>`_.
Ephemeral disk encryption
-------------------------
The ephemeral disk encryption feature addresses data privacy. The
ephemeral disk is a temporary work space used by the virtual host
operating system. Without encryption, sensitive user information could
be accessed on this disk, and vestigial information could remain after
the disk is unmounted.
The ephemeral disk encryption feature, can interface with a key
management service through a secure wrapper and support data isolation
by providing ephemeral disk encryption keys on a per-tenant basis.
Back-end key storage is recommended for enhanced security (for example,
an HSM or KMIP server can be used as a barbican back-end secret store).
For more details, see the `Ephemeral disk encryption documentation
<https://docs.openstack.org/security-guide/tenant-data/data-encryption.html#ephemeral-disk-encryption>`_.
Sahara
------
Sahara generates and stores several passwords during the course of
operation. To harden saharas usage of passwords it can be instructed
to use an external key manager for storage and retrieval of these
secrets. To enable this feature, there must first be an OpenStack Key
Manager service deployed within the stack.
With a Key Manager service deployed on the stack, sahara must be
configured to enable the external storage of secrets. Sahara uses the
Castellan library to interface with the OpenStack Key Manager service.
This library provides configurable access to a key manager.
For more information, see the `Sahara advanced configuration guide <https://docs.openstack.org/developer/sahara/userdoc/advanced.configuration.guide.html#external-key-manager-usage>`_.
Magnum
------
To provide access to Docker Swarm or Kubernetes using the native clients
(``docker`` or ``kubectl`` respectively) magnum uses TLS certificates. To store
the certificates, it is recommended to use Barbican , or the Magnum
Database (``x590keypair``).
A local directory can also be used (``local``), but is considered insecure and
not suitable for a production enviroment.
For more details on setting up a certificate manager for Magnum, see the `Container Infrastructure Management service <https://docs.openstack.org/project-install-guide/container-infrastructure-management/newton/install.html>`_ documentation.
Octavia/LBaaS
-------------
The LBaaS (Load-Balancer-as-a-Service) feature of Neutron and the
Octavia project need certificates and their private keys to provide
load balancing for TLS connections. Barbican can be used to store this
sensitive information.
For more details, see `How to create a TLS Loadbalancer <https://wiki.openstack.org/wiki/Network/LBaaS/docs/how-to-create-tls-loadbalancer>`_. and `Deploy a TLS-terminated HTTPS load balancer <https://docs.openstack.org/developer/octavia/guides/basic-cookbook.html#deploy-a-tls-terminated-https-load-balancer>`_.
Swift
-----
Symmetric keys can be used to encrypt Swift containers to mitigate the risk of
users data being read if an unauthorised party were to gain physical access to
a disk.
For more details, see `Object Encryption <https://docs.openstack.org/swift/pike/overview_encryption.html>`_ within the official swift
documentation.
Passwords in Config Files
-------------------------
The configuration files for the OpenStack services contain a number of
passwords which are in plain text. These include, for instance, the
passwords used by service users to authenticate to keystone to validate
keystone tokens.
There is no current solution to obfuscate these passwords. It is recommended
that these files be appropriately secured by file permissions.
There is currently an effort underway to store these secrets in a Castellan
back-end and then have oslo.config use Castellan to retrieve these secrets.

View File

@ -0,0 +1,21 @@
================================
Summary of existing technologies
================================
Within OpenStack, there are two solutions recommended for secrets
managment, those being `Barbican <https://docs.openstack.org/barbican/latest/>`_ and `Castellan <https://docs.openstack.org/castellan/latest/>`_. This chapter will
outline different scenarios to help an operator make a choice on which
key manager to use.
A third non supported method is Fixed/Hardcoded keys. It is known that some
OpenStack services have the option to specify keys in their configuration
files. This is the least secure way to operate and we do not recommend
this for any sort of production environment.
Other solutions exist including KeyWhiz, Confidant, Conjur, EJSON, Knox
and Red October, however it is outside the scope of this document to cover
every Key Manager available.
For storage of secrets, it's strongly recommended to a Hardware Security
Modules (HSMs). HSMs can come in multiple forms. The traditional device is a
rack mounted appliance such as the one `shown in the following blog post <https://vakwetu.wordpress.com/2015/11/30/barbican-and-dogtagipa/>`_.