85 lines
3.2 KiB
ReStructuredText
85 lines
3.2 KiB
ReStructuredText
..
|
|
Copyright 2018 AT&T Intellectual Property.
|
|
All Rights Reserved.
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
.. _encryption:
|
|
|
|
Data Encryption
|
|
===============
|
|
|
|
Deckhand supports encrypting the ``data`` section of documents at-rest to
|
|
secure sensitive data. This encryption behavior is triggered by setting
|
|
``metadata.storagePolicy: encrypted``. It is solely the document author's
|
|
responsibility to decide the appropriate storagePolicy for the data contained
|
|
in the document.
|
|
|
|
.. note::
|
|
|
|
Note that encryption of document data incurs **runtime overhead** as the
|
|
price of encryption is performance. As a general rule, the more documents
|
|
with ``storagePolicy: encrypted``, the longer it will take to render the
|
|
documents, particularly because `Barbican`_ has a built-in `restriction`_
|
|
around retrieving only one encrypted payload a time. This means that
|
|
if 50 documents have ``storagePolicy: encrypted`` within a revision, then
|
|
Deckhand must perform 50 API calls to Barbican when rendering the documents
|
|
for that revision.
|
|
|
|
Encrypted documents, like cleartext documents, are stored in Deckhand's
|
|
database, except the ``data`` section of each encrypted document is replaced
|
|
with a reference to Barbican.
|
|
|
|
Supported Data Types
|
|
--------------------
|
|
|
|
`Barbican`_ supports encrypting `any`_ data type via its "opaque" secret type.
|
|
Thus, Deckhand supports encryption of any data type by utilizing this
|
|
secret type.
|
|
|
|
However, Deckhand will attempt to use Barbican's `other`_ secret types where
|
|
possible. For example, Deckhand will use "public" for document types with kind
|
|
``PublicKey``.
|
|
|
|
.. _data-redaction:
|
|
|
|
Data Redaction
|
|
==============
|
|
|
|
Deckhand supports redacting sensitive document data, including:
|
|
|
|
* ``data`` section:
|
|
|
|
* to avoid exposing the Barbican secret reference, in the case of the
|
|
"GET documents" endpoint
|
|
* to avoid exposing actual secret payloads, in the case of the
|
|
"GET rendered-documents" endpoint
|
|
|
|
* ``substitutions[n].src|dest`` sections:
|
|
|
|
* to avoid reverse-engineering where sensitive data is substituted from or
|
|
into (in case the sensitive data is derived via :ref:`substitution`)
|
|
|
|
.. note::
|
|
|
|
Document sections related to :ref:`layering` do not require redaction because
|
|
secret documents are :ref:`control-documents`, which cannot be layered
|
|
together.
|
|
|
|
See the :ref:`api-ref` for more information on how to redact sensitive data.
|
|
|
|
.. _Barbican: https://docs.openstack.org/barbican/latest/api/
|
|
.. _restriction: https://docs.openstack.org/barbican/latest/api/reference/secrets.html#get-v1-secrets
|
|
.. _any: https://github.com/openstack/barbican/blob/7991f8b4850d76d97c3482428638f788f5798a56/barbican/plugin/interface/secret_store.py#L272
|
|
.. _other: https://docs.openstack.org/barbican/latest/api/reference/secret_types.html
|