Spec: Pegleg secret generation and encryption
This patchset adds a spec outlining the work effort and high-level implementation considerations for adding the ability to generate, encrypt, and decrypt secrets from Pegleg. Change-Id: Iacc99008be96a4b0bac145d5fa84143cc64e9b67 Story: 2003708 Task: 26363
This commit is contained in:
Matt McEuen
parent
145307c84b
commit
d1fca12693
@ -1,8 +0,0 @@
|
|||||||
.. placeholder:
|
|
||||||
|
|
||||||
===========
|
|
||||||
Placeholder
|
|
||||||
===========
|
|
||||||
|
|
||||||
This file is a placeholder and should be deleted when the first spec is moved
|
|
||||||
to this directory.
|
|
||||||
372
specs/approved/pegleg-secrets.rst
Normal file
372
specs/approved/pegleg-secrets.rst
Normal file
@ -0,0 +1,372 @@
|
|||||||
|
..
|
||||||
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||||
|
License.
|
||||||
|
|
||||||
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: template
|
||||||
|
single: creating specs
|
||||||
|
|
||||||
|
=======================================
|
||||||
|
Pegleg Secret Generation and Encryption
|
||||||
|
=======================================
|
||||||
|
|
||||||
|
Pegleg is responsible for shepherding deployment manifest documents from their
|
||||||
|
resting places in Git repositories to a consumable format that is ready
|
||||||
|
for ingestion into Airship. This spec expands its responsibility to
|
||||||
|
account for secure generation and encryption of secrets that are
|
||||||
|
required within an Airship-based deployment.
|
||||||
|
|
||||||
|
Links
|
||||||
|
=====
|
||||||
|
|
||||||
|
The work to author and implement this spec will be tracked under this
|
||||||
|
`Storyboard Story`_.
|
||||||
|
|
||||||
|
Problem description
|
||||||
|
===================
|
||||||
|
|
||||||
|
Airship supports the ability to identify secret information
|
||||||
|
required for functioning deployments, such as passwords and keys; to
|
||||||
|
ingest it into the site in a least-privilege-oriented fashion; and
|
||||||
|
to encrypt it at rest within Deckhand. However, lifecycle management of
|
||||||
|
the secrets outside the site should be made automatable and
|
||||||
|
repeatable, to facilitate operational needs such as periodic password
|
||||||
|
rotation, and to ensure that unencrypted secrets are only accessible by
|
||||||
|
authorized individuals.
|
||||||
|
|
||||||
|
Impacted components
|
||||||
|
===================
|
||||||
|
|
||||||
|
The following Airship components will be impacted by this solution:
|
||||||
|
|
||||||
|
#. Pegleg: enhanced to generate, rotate, encrypt, and decrypt secrets.
|
||||||
|
#. Promenade: PKICatalog will move to Pegleg.
|
||||||
|
#. Treasuremap: site manifests augmented to support the updated Secrets schema.
|
||||||
|
#. Airship-in-a-Bottle: site manifests augmented to support the updated
|
||||||
|
Secrets schema.
|
||||||
|
|
||||||
|
Proposed change
|
||||||
|
===============
|
||||||
|
|
||||||
|
PeglegManagedDocument
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
With this spec, the role of Pegleg grows from being a custodian of deployment
|
||||||
|
manifests to additionally being the author of certain manifests. A new YAML
|
||||||
|
schema will be created to describe these documents:
|
||||||
|
``pegleg/PeglegManagedDocument/v1``.
|
||||||
|
Documents of this type will have one or both of the following data elements,
|
||||||
|
although more may be added in the future: ``generated``, ``encrypted``.
|
||||||
|
PeglegManagedDocuments serve as wrappers around other documents, and the
|
||||||
|
wrapping serves to capture additional metadata that is necessary, but
|
||||||
|
separate from the managed document proper.
|
||||||
|
The managed document data will live in the ``data.managedDocument`` portion
|
||||||
|
of a PeglegManagedDocument.
|
||||||
|
|
||||||
|
If a PeglegManagedDocument is ``generated``, then its contents have been
|
||||||
|
created by Pegleg, and it must include provenance information per this
|
||||||
|
example::
|
||||||
|
|
||||||
|
schema: pegleg/PeglegManagedDocument/v1
|
||||||
|
metadata:
|
||||||
|
name: matches-document-name
|
||||||
|
schema: deckhand/Document/v1
|
||||||
|
labels:
|
||||||
|
matching: wrapped-doc
|
||||||
|
layeringDefinition:
|
||||||
|
abstract: false
|
||||||
|
# Pegleg will initially support generation at site level only
|
||||||
|
layer: site
|
||||||
|
storagePolicy: encrypted
|
||||||
|
data:
|
||||||
|
generated:
|
||||||
|
at: <timestamp>
|
||||||
|
by: <author>
|
||||||
|
specifiedBy:
|
||||||
|
repo: <...>
|
||||||
|
reference: <git ref-head or similar>
|
||||||
|
path: <PKICatalog/PassphraseCatalog details>
|
||||||
|
managedDocument:
|
||||||
|
metadata:
|
||||||
|
storagePolicy: encrypted
|
||||||
|
schema: <as appropriate for wrapped document>
|
||||||
|
<metadata from parent PeglegManagedDocument>
|
||||||
|
<any other metadata as appropriate>
|
||||||
|
data: <generated data>
|
||||||
|
|
||||||
|
If a PeglegManagedDocument is ``encrypted``, then its contents have been
|
||||||
|
encrypted by Pegleg, and it must include provenance information per this
|
||||||
|
example::
|
||||||
|
|
||||||
|
schema: pegleg/PeglegManagedDocument/v1
|
||||||
|
metadata:
|
||||||
|
name: matches-document-name
|
||||||
|
schema: deckhand/Document/v1
|
||||||
|
labels:
|
||||||
|
matching: wrapped-doc
|
||||||
|
layeringDefinition:
|
||||||
|
abstract: false
|
||||||
|
layer: matching-wrapped-doc
|
||||||
|
storagePolicy: encrypted
|
||||||
|
data:
|
||||||
|
encrypted:
|
||||||
|
at: <timestamp>
|
||||||
|
by: <author>
|
||||||
|
managedDocument:
|
||||||
|
metadata:
|
||||||
|
storagePolicy: encrypted
|
||||||
|
schema: <as appropriate for wrapped document>
|
||||||
|
<metadata from parent PeglegManagedDocument>
|
||||||
|
<any other metadata as appropriate>
|
||||||
|
data: <encrypted string blob>
|
||||||
|
|
||||||
|
A PeglegManagedDocument that is both generated via a Catalog, and encrypted
|
||||||
|
(as specified by the catalog) will contain both ``generated`` and
|
||||||
|
``encrypted`` stanzas.
|
||||||
|
|
||||||
|
Note that this ``encrypted`` has a different purpose than the Deckhand
|
||||||
|
``storagePolicy: encrypted`` metadata, which indicates an *intent* for Deckhand
|
||||||
|
to store a document encrypted at rest in the cluster. The two can be used
|
||||||
|
together to ensure security, however: if a document is marked as
|
||||||
|
``storagePolicy: encrypted``, then automation may validate that it is only
|
||||||
|
persisted (e.g. to a Git repository) if it is in fact encrypted within
|
||||||
|
a PeglegManagedDocument.
|
||||||
|
|
||||||
|
Document Generation
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Document generation will follow the pattern established by Promenade's
|
||||||
|
PKICatalog pattern. In fact, PKICatalog management responsibility will move
|
||||||
|
to Pegleg as part of this effort. The types of documents that are expected
|
||||||
|
to be generated are certificates and keys, which are defined via PKICatalog
|
||||||
|
documents now, and passphrases, which will be defined via a new
|
||||||
|
``pegleg/PassphraseCatalog/v1`` document. Longer-term, these specifications
|
||||||
|
may be combined, or split further (into a CertificateCatalog and
|
||||||
|
KeypairCatalog), but this is not needed in the initial implementation in
|
||||||
|
Pegleg. A collection of manifests
|
||||||
|
may define more than one of each of these secret catalog documents if desired.
|
||||||
|
|
||||||
|
The documents generated via PKICatalog and PassphraseCatalog will follow the
|
||||||
|
PeglegManagedDocument schema above; note that this is a change to existing
|
||||||
|
PKICatalog behavior. The PKICatalog schema and associated code should be
|
||||||
|
copied to Pegleg (and renamed to ``pegleg/PKICatalog/v1``), and during a
|
||||||
|
transition period the old and new PKICatalog implementations will exist
|
||||||
|
side-by-side with slightly different semantics. Promenade's PKICatalog can
|
||||||
|
be removed once all deployment manifests have been updated to use the new one.
|
||||||
|
|
||||||
|
Pegleg will place generated document files in ``<site>/secrets/passphrases/``,
|
||||||
|
``<site>/secrets/certificates``, or ``<site>/secrets/keypairs`` as appropriate:
|
||||||
|
|
||||||
|
* The generated filenames for passphrases will follow the pattern
|
||||||
|
``<passphrase-doc-name>.yaml``.
|
||||||
|
* The generated filenames for certificate authorities will follow the pattern
|
||||||
|
``<ca-name>_ca.yaml``.
|
||||||
|
* The generated filenames for certificates will follow the pattern
|
||||||
|
``<ca-name>_<certificate-doc-name>_certificate.yaml``.
|
||||||
|
* The generated filenames for certificate keys will follow the pattern
|
||||||
|
``<ca-name>_<certificate-doc-name>_key.yaml``.
|
||||||
|
* The generated filenames for keypairs will follow the pattern
|
||||||
|
``<keypair-doc-name>.yaml``.
|
||||||
|
* Dashes in the document names will be converted to underscores for consistency.
|
||||||
|
|
||||||
|
A PassphraseCatalog will capture the following example structure::
|
||||||
|
|
||||||
|
schema: pegleg/PassphraseCatalog/v1
|
||||||
|
metadata:
|
||||||
|
schema: metadata/Document/v1
|
||||||
|
name: cluster-passphrases
|
||||||
|
layeringDefinition:
|
||||||
|
abstract: false
|
||||||
|
layer: site
|
||||||
|
storagePolicy: cleartext
|
||||||
|
data:
|
||||||
|
passphrases:
|
||||||
|
- document_name: osh-nova-password
|
||||||
|
description: Service password for Nova
|
||||||
|
encrypted: true
|
||||||
|
- document_name: osh-nova-oslo-db-password
|
||||||
|
description: Database password for Nova
|
||||||
|
encrypted: true
|
||||||
|
length: 12
|
||||||
|
|
||||||
|
The nonobvious bits of the document described above are:
|
||||||
|
|
||||||
|
* ``encrypted`` is optional, and denotes whether the generated
|
||||||
|
PeglegManagedDocument will be ``encrypted``, as well as whether the wrapped
|
||||||
|
document will have ``storagePolicy: encrypted`` or
|
||||||
|
``storagePolicy: cleartext`` metadata.
|
||||||
|
If absent, ``encrypted`` defaults to ``true``.
|
||||||
|
* ``document_name`` is required, and is used to create the filename of the
|
||||||
|
generated PeglegManagedDocument manifest, and the ``metadata.name`` of
|
||||||
|
the wrapped ``deckhand/Passphrase/v1`` document. In both cases, Pegleg will
|
||||||
|
replace dashes in the ``document_name`` with underscores.
|
||||||
|
* ``length`` is optional, and denotes the length in characters of the
|
||||||
|
generated cleartext passphrase data. If absent, ``length`` defaults
|
||||||
|
to ``24``.
|
||||||
|
* ``description`` is optional.
|
||||||
|
|
||||||
|
The ``encrypted`` key will be added to the PKICatalog schema, and adds the same
|
||||||
|
semantics to PKICatalog-based generation as are described above for
|
||||||
|
PassphraseCatalog.
|
||||||
|
|
||||||
|
Pegleg CLI Changes
|
||||||
|
------------------
|
||||||
|
|
||||||
|
The Pegleg CLI interface will be extended as follows. These
|
||||||
|
commands will create PeglegManagedDocument manifests in the local repository.
|
||||||
|
Committing and pushing the changes will be left to the
|
||||||
|
operator or to script-based automation.
|
||||||
|
|
||||||
|
For the CLI commands below which encrypt or decrypt secrets, an environment
|
||||||
|
variable (e.g. ``$PEGLEG_KEY`` will be use to capture the key/passphrase to use.
|
||||||
|
``pegleg site secrets rotate`` will use a second variable
|
||||||
|
(e.g. ``$PEGLEG_PREVIOUS_KEY``) to hold the key/passphrase being rotated
|
||||||
|
out.
|
||||||
|
|
||||||
|
``pegleg site secrets generate passphrases``: Generate passphrases according to
|
||||||
|
all PassphraseCatalog documents in the site.
|
||||||
|
Note that regenerating passphrases can be accomplished
|
||||||
|
simply by re-running ``pegleg site secrets generate passphrases``.
|
||||||
|
|
||||||
|
``pegleg site secrets generate pki``: Generate certificates and keys according
|
||||||
|
to all PKICatalog documents in the site.
|
||||||
|
Note that regenerating certificates can be accomplished
|
||||||
|
simply by re-running ``pegleg site secrets generate pki``.
|
||||||
|
|
||||||
|
``pegleg site secrets generate``: Combines the two commands above.
|
||||||
|
May be expanded in the future to include other manifest generation activities.
|
||||||
|
|
||||||
|
``pegleg site bootstrap``: For now, a synonym for
|
||||||
|
``pegleg site secrets generate``,
|
||||||
|
and may be expanded in the future to include other bootstrapping activities.
|
||||||
|
|
||||||
|
``pegleg site secrets encrypt``: Encrypt all site documents which have
|
||||||
|
``metadata.storagePolicy: encrypted``, and which are not already encrypted
|
||||||
|
within a wrapping PeglegManagedDocument. Note that the
|
||||||
|
``pegleg site secrets generate`` commands encrypt generated secrets as
|
||||||
|
specified, so ``pegleg site secrets encrypt`` is intended mainly for
|
||||||
|
external-facing secrets which a deployment engineer brings to the site
|
||||||
|
manifests.
|
||||||
|
The output PeglegManagedDocument will be written back to the filename that
|
||||||
|
served as its source.
|
||||||
|
|
||||||
|
``pegleg site secrets decrypt <document YAML file>``: Decrypt a specific
|
||||||
|
PeglegManagedDocument manifest, unwrapping it and outputting the cleartext
|
||||||
|
original document YAML to standard output. This is intended to be used when
|
||||||
|
an authorized deployment engineer needs to determine a particular cleartext
|
||||||
|
secret for a specific operational purpose.
|
||||||
|
|
||||||
|
``pegleg site secrets rotate``: This action re-encrypts encrypted secrets
|
||||||
|
with a new key/passphrase, and it takes the previously-used key and a new
|
||||||
|
key as input. It accomplishes its task via two activities:
|
||||||
|
|
||||||
|
* For encrypted secrets that were imported from outside of Pegleg
|
||||||
|
(i.e. PeglegManagedDocuments which lack the ``generated`` stanza),
|
||||||
|
decrypt them with the old key (in-memory), re-encrypt them with
|
||||||
|
the new key, and output the results.
|
||||||
|
* Perform a fresh ``pegleg site secrets generate`` process using the new key.
|
||||||
|
This will replace all ``generated`` secrets with new secret values
|
||||||
|
for added security. There is an assumption here that the only actors
|
||||||
|
that need to know generated secrets are the services within the
|
||||||
|
Airship-managed cluster, not external services or deployment engineers,
|
||||||
|
except perhaps for point-in-time troubleshooting or operational
|
||||||
|
exercises.
|
||||||
|
|
||||||
|
Driving deployment of a site directly via Pegleg is follow-on functionality
|
||||||
|
which will
|
||||||
|
collect site documents, use them to create the ``genesis.sh`` script, and then
|
||||||
|
interact directly with Shipyard to drive deployments. Its details are beyond
|
||||||
|
the scope of this spec, but when implemented, it should decrypt documents
|
||||||
|
wrapped by applicable PeglegManagedDocuments at the lst responsible moment,
|
||||||
|
and take care not to write, log, or stdout them to disk as cleartext.
|
||||||
|
|
||||||
|
Note that existing ``pegleg collect`` functionality should **not** be changed
|
||||||
|
to decrypt encrypted secrets; this is because it writes its output to disk.
|
||||||
|
If ``pegleg collect`` is called, at this point in time, the
|
||||||
|
PeglegManagedDocuments will be written (encrypted) to disk.
|
||||||
|
To enable special case full site secret decryption, a ``--force-decrypt`` flag
|
||||||
|
will be added to ``pegleg collect`` to do this under controlled circumstances,
|
||||||
|
and to help bridge the gap with existing CICD pipelines until Pegleg-driven
|
||||||
|
site deployment is in place. It will leverage the ``$PEGLEG_KEY``
|
||||||
|
variable described above.
|
||||||
|
|
||||||
|
Secret Generation
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
The ``rstr`` library should be invoked to generate secrets of the
|
||||||
|
appropriate length and character set.
|
||||||
|
This library uses the ``os.urandom()`` function,
|
||||||
|
which in turn leverages ``/dev/urandom`` on Linux,
|
||||||
|
and it is suitable for cryptographic purposes.
|
||||||
|
|
||||||
|
Characters in generated secrets will be evenly distributed across lower-
|
||||||
|
and upper-case letters, digits, and punctuation in
|
||||||
|
!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~. Note this is equivalent to the union of
|
||||||
|
Python string.ascii_letters, string.digits, and string.punctuation.
|
||||||
|
|
||||||
|
Secret Encryption
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Details around encryption will be defined in a follow-on patch set to this spec.
|
||||||
|
|
||||||
|
Security impact
|
||||||
|
===============
|
||||||
|
|
||||||
|
These changes will result in a system that handles site secrets in a highly
|
||||||
|
secure manner, in the face of multiple roles and day 2 operational needs.
|
||||||
|
|
||||||
|
Performance impact
|
||||||
|
==================
|
||||||
|
|
||||||
|
Performance impact to existing flows will be minimal. Pegleg will need to
|
||||||
|
additionally decrypt secrets as part of site deployment, but this will be
|
||||||
|
an efficient operation performed once per deployment.
|
||||||
|
|
||||||
|
Alternatives
|
||||||
|
============
|
||||||
|
|
||||||
|
The Python ``secrets`` library presents a convenient interface for generating
|
||||||
|
random strings. However, it was introduced in Python 3.6, and it would be
|
||||||
|
limiting to introduce this constraint on Airship CICD pipelines.
|
||||||
|
|
||||||
|
The ``strgen`` library presents an even more convenient interface for
|
||||||
|
generating pseudo-random strings; however, it leverages the Python ``random``
|
||||||
|
library, which is unsuitably random for cryptographic purposes.
|
||||||
|
|
||||||
|
Deckhand already supports a ``storagePolicy`` element which indicates whether
|
||||||
|
whether Deckhand will persist document data in an encrypted state, and this
|
||||||
|
flag could have been re-used by Pegleg to indicate whether a secret is
|
||||||
|
(or should be) encrypted. However, "should this data be encrypted" is a
|
||||||
|
fundamentally different question than "is this data encrypted now", and
|
||||||
|
additional metadata-esque parameters (``generated``, ``generatedLength``)
|
||||||
|
were desired as well, so this proposal adds ``data.encrypted`` to indicate
|
||||||
|
the point-in-time encryption status. ``storagePolicy`` is still valuable
|
||||||
|
in this context to make sure everything that *should* be encrypted *is*,
|
||||||
|
prior to performing actions with it (e.g. Git commits).
|
||||||
|
|
||||||
|
This proposed implementation writes the output of generation/encryption events
|
||||||
|
back to the same source files from which the original data came. This is a
|
||||||
|
destructive operation; however, it wasn't evident that it is problematic in
|
||||||
|
any anticipated workflow. In addition, it sidesteps challenges around
|
||||||
|
naming of generated files, and cleanup of original files.
|
||||||
|
|
||||||
|
Implementation
|
||||||
|
==============
|
||||||
|
|
||||||
|
Please refer to the `Storyboard Story`_ for implementation planning information.
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
============
|
||||||
|
|
||||||
|
This work should be based on the patchset to add `Git branch and revision
|
||||||
|
support`_ to Pegleg, if it is not merged by the time implementation begins.
|
||||||
|
This patchset alters the CLI interface and Git repository management code,
|
||||||
|
and basing on it will avoid future refactoring.
|
||||||
|
|
||||||
|
References
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. _Storyboard Story: https://storyboard.openstack.org/#!/story/2003708
|
||||||
|
.. _Git branch and revision support: https://review.openstack.org/#/c/577886/
|
||||||
Loading…
x
Reference in New Issue
Block a user