Giters

repository-service-tuf / repository-service-tuf

Umbrella Repository Service for TUF

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Task: add documentation for metadata update

MVrachev opened this issue · comments

commented

What is the task about?

Describe how our users can do a successful metadata update.

We want to cover in the doc:

  • what can be updated from the metadata update RSTUF CLI command
  • explaining how offline keys can be updated
  • explaining the process of how to correctly update the online key

Code of Conduct

  • I agree to follow this project's Code of Conduct
commented

I think it's really important to describe well as an algorithm how to update the online key.
I think this should happen as follows:

  1. Append a new keyid to the RSTUF_*_KEYVAULT_KEYS env variable
  2. Finish a successful metadata update ceremony from the RSTUF CLI.
  3. Call POST /api/v1/metadata with the new payload.
  4. Restart your container

It's important that you do steps 1 to 3 before you restart your container so that the new root.json has the new keyid otherwise you will end up with an invalid repository that cannot sign.
If you forgot to do step 1 you will end up with a new root with a new online key id which doesn't match the key used by your signer.
If you forgot to do steps 2 or 3 you won't have a new root.json and you will continue using the old signer based on the old online key.

commented

After a conversation with @kairoaraujo we came up with the following steps for AWS KeyVault online key rotation

  1. Create AWS key
  2. Update env variable
  3. Restart containers
    1. Init all possible signers
  4. Do a "metadata update" ceremony
  5. Publish new root version