deckhand/doc/source/users/encryption.rst
Felipe Monteiro f711a83ee7 docs: Add documentation on data redaction
This patch set adds documentation related to data redaction in
order to capture the purpose behind it and how it adds an
added layer of security to Deckhand.

Change-Id: Icb28970684a9026fda200273a14d9ba421f627d7
2018-10-20 14:48:19 -04:00

3.2 KiB

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

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 substitution)

Note

Document sections related to layering do not require redaction because secret documents are control-documents, which cannot be layered together.

See the api-ref for more information on how to redact sensitive data.