OTA Connect Developer Guide

Change signature thresholds

One way you can keep your software repository more secure is by adding extra signing keys, and then setting up key thresholds to require metadata to be signed by multiple different keys. By default, each role on the repository has one signing key and a threshold of one. For more security in the Root role, for example, you might want to create 5 different keys, keep them locked up at different locations around the world, and require that at least three of the keys sign off on any change to Root metadata. You can also use key thresholds for delegations.

To change the thresholds for signing Root metadata:

  1. Generate a new Root key.

    garage-sign key generate --repo <localreponame> --name root-key-1 --type rsa
  2. Add the new Root key to the root.json file.

    garage-sign root key add --repo <localreponame> --key-name </path/to/public-root-key-1>
  3. If you need more Root keys, repeat steps 1 and 2.

  4. In the Roles folder of your local software repository, open the Unsigned folder, and then open the root.json file.

  5. Depending on the threshold that you want to change, in the signed block, in the root subsection, for the keyids object, specify the list of valid keys that you want to use for signing.

    You can find the list of all your Root keys in the keys subsection.

    The new version of Root metadata should be valid according to the rules of the previous and current versions. So you must sign Root metadata with the threshold of keys specified in the previous Root metadata file and the threshold of keys specified in the new Root metadata file. For more information, see the related section of the Uptane standard.
  6. For the version object, specify the version number of the new Root metadata.

  7. Sign the root.json file with the same number of valid signatures that you specified in the Root key threshold.

    garage-sign root sign \
      --repo <localreponame> \
      -k </path/to/public-root-key-1> \
      -k </path/to/public-root-key-2> \
      --expires <root-metadata-expiry-date>
  8. Push the modified root.json file to OTA Connect.

    garage-sign root push \
      --repo <localreponame>

To change the threshold of delegations, modify the .json file with the delegation metadata in the same way as the root.json file.

To learn more about the garage-sign commands and options, see its reference documentation.