Update signing docs for Zuul v3
Update the artifact signing key rotation process documentation for the new Zuul v3 status quo. Also note that revocation certificates should use distinct filenames per cycle so that they don't get overwritten. Change-Id: Ia7512cc7bd0b1ed52e99271e7d83f05e7bc57918
This commit is contained in:
Jeremy Stanley
parent
30ebbfc276
commit
fd75fadee3
|
|
@ -5,42 +5,44 @@
|
|||
Signing System
|
||||
##############
|
||||
|
||||
This machine corresponds to the ``signing`` node label in job
|
||||
configuration, holding an unencrypted copy of the OpenPGP signing
|
||||
subkey for ``OpenStack Infra (Some Cycle)
|
||||
<infra-root@openstack.org>`` used to create detached signatures for
|
||||
Our standard signing automation leverages an OpenPGP signing subkey,
|
||||
encrypted as a Zuul secret, to create detached signatures for
|
||||
release artifacts (tarballs, wheels, et cetera) and to sign and push
|
||||
Git tags as part of our managed release automation. It only runs CI
|
||||
jobs for tasks which require access to this key, using only vetted
|
||||
tools and scripts reviewed by the Infra team.
|
||||
Git tags as part of our managed release automation. The master key
|
||||
corresponding to this subkey is replaced near the start of each new
|
||||
development cycle and set to expire soon after the cycle is
|
||||
scheduled to conclude (with enough overlap to allow for graceful
|
||||
replacement).
|
||||
|
||||
|
||||
At a Glance
|
||||
===========
|
||||
|
||||
:Hosts:
|
||||
* signing*.ci.openstack.org
|
||||
:Puppet:
|
||||
* :file:`modules/openstack_project/manifests/signing_node.pp`
|
||||
:Secrets:
|
||||
* `gpg_key
|
||||
<https://git.openstack.org/cgit/openstack-infra/project-config/tree/zuul.d/secrets.yaml>`_
|
||||
:Roles:
|
||||
* `add-gpgkey
|
||||
<https://docs.openstack.org/infra/zuul-jobs/roles.html#role-add-gpgkey>`_
|
||||
* `sign-artifacts
|
||||
<https://docs.openstack.org/infra/zuul-jobs/roles.html#role-sign-artifacts>`_
|
||||
|
||||
|
||||
Key Management Overview
|
||||
=======================
|
||||
|
||||
The signing server is a fairly typical long-lived job node,
|
||||
distinguished primarily by having the signing subkey pair installed
|
||||
by Puppet into the job runner account's home directory from binary
|
||||
blobs in hiera. These blobs correspond to the
|
||||
``~/.gnupg/pubring.gpg`` and ``~/.gnupg/secring.gpg`` files of a
|
||||
freshly initialized gpg config after importing a minimal unencrypted
|
||||
export on the management bastion of only the desired signing subkey
|
||||
from the ``/root/signing.gunpg`` directory.
|
||||
The signing system is implemented as a set of Zuul v3 jobs; these
|
||||
utilize the signing subkey via an encrypted Zuul secret imported
|
||||
into a job's ``~/.gnupg/secring.gpg`` at runtime. It's used by jobs
|
||||
to create detached signatures of release artifacts and to sign Git
|
||||
tags under release management automation.
|
||||
|
||||
|
||||
Storage
|
||||
-------
|
||||
|
||||
While the signing subkey is present unencrypted on this system, the
|
||||
While the signing subkey is installed unencrypted on some job nodes,
|
||||
so that it can be used unattended by job automation, the
|
||||
corresponding master key is kept symmetrically encrypted in the root
|
||||
home directory of the Infra systems management bastion instead. At
|
||||
the time of key creation a revocation certificate is also generated,
|
||||
|
|
@ -56,10 +58,11 @@ similar to what `the Debian Project does for its archive keys
|
|||
Rotation
|
||||
--------
|
||||
|
||||
The master key is rotated at the start of each development cycle,
|
||||
The master key is rotated at the start of each development cycle
|
||||
(usually shortly after cycle-trailing deliverables are released),
|
||||
signed by a majority of Infra root sysadmins before being put into
|
||||
service, and has an expiration date set for shortly after the end of
|
||||
the targeted development cycle. The new key should also be signed by
|
||||
service, and has an expiration date set for a month after the end of
|
||||
the targeted development cycle. The newly-created key gets signed by
|
||||
the old, and this signature pushed to the public keyserver network.
|
||||
New key fingerprints are also submitted to the openstack/releases
|
||||
repository, for publication on the releases.openstack.org Web site.
|
||||
|
|
@ -222,12 +225,13 @@ case extreme case that this master key itself becomes inaccessible,
|
|||
for example because the decryption passphrase is lost (under any
|
||||
other circumstances, a revocation certificate with a more detailed
|
||||
description can be generated using the master key on an as-needed
|
||||
basis):
|
||||
basis). Replace ``some`` in the output filename with the lower-cased
|
||||
cycle name:
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
||||
root@puppetmaster:~# gpg --homedir signing.gnupg --output \
|
||||
> signing.gnupg/revoke.asc --gen-revoke 0x120D3C23C6D5584D
|
||||
> signing.gnupg/some.revoke.asc --gen-revoke 0x120D3C23C6D5584D
|
||||
sec 2048R/0x120D3C23C6D5584D 2016-07-07 OpenStack Infra (Some Cycle) <infra-root@openstack.org>
|
||||
|
||||
Create a revocation certificate for this key? (y/N) y
|
||||
|
|
@ -394,8 +398,8 @@ GnuPG directory:
|
|||
gpg: secret keys imported: 1
|
||||
|
||||
Check that the exported version does not contain a usable primary
|
||||
secret key by listing all secret keys and looking for a `sec#` in
|
||||
front of it instead of just `sec`:
|
||||
secret key by listing all secret keys and looking for a ``sec#`` in
|
||||
front of it instead of just ``sec``:
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
||||
|
|
@ -491,13 +495,13 @@ public master key:
|
|||
> --export 0x120d3c23c6d5584d6fc2464664dbb05acc5e7c28 ) > \
|
||||
> 0x120d3c23c6d5584d6fc2464664dbb05acc5e7c28.txt
|
||||
|
||||
Add the file to a change for the `openstack/releases` repo placing
|
||||
it in the `doc/source/static` directory, and then link it similarly
|
||||
Add the file to a change for the ``openstack/releases`` repo placing
|
||||
it in the ``doc/source/static`` directory, and then link it similarly
|
||||
to other exported public keys are linked in the `Cryptographic
|
||||
Signatures
|
||||
<https://releases.openstack.org/#cryptographic-signatures>` section
|
||||
of `doc/source/index.rst` (noting the appropriate end date for use of
|
||||
the prior key as the start date for the new one).
|
||||
of ``doc/source/index.rst`` (noting the appropriate end date for use
|
||||
of the prior key as the start date for the new one).
|
||||
|
||||
|
||||
Attestation
|
||||
|
|
@ -586,9 +590,10 @@ and push the signature back to the keyserver network:
|
|||
gpg: sending key 0x120D3C23C6D5584D to hkps server hkps.pool.sks-keyservers.net
|
||||
|
||||
Also, please retrieve a copy of the
|
||||
``/root/signing.gnupg/revoke.asc`` fallback revocation certificate
|
||||
from the management bastion and keep it stashed somewhere secure,
|
||||
for emergency use in the (hopefully very unlikely) event that our
|
||||
OpenPGP master private key is completely lost to us (for example, if
|
||||
we lose the file containing its decryption passphrase and all
|
||||
backups thereof).
|
||||
``/root/signing.gnupg/some.revoke.asc`` fallback revocation
|
||||
certificate (``some`` to be replaced with the lower-cased release
|
||||
name) from the management bastion and keep it stashed somewhere
|
||||
secure, for emergency use in the (hopefully very unlikely) event
|
||||
that our OpenPGP master private key is completely lost to us (for
|
||||
example, if we lose the file containing its decryption passphrase
|
||||
and all backups thereof).
|
||||
|
|
|
|||
Loading…
Reference in New Issue