| commit | 4817580cf7e910a17d1ce6aada2371134984cf96 | [log] [tgz] |
|---|---|---|
| author | Ethan Lowman <ethan.lowman@datadoghq.com> | Mon Nov 29 11:17:47 2021 -0500 |
| committer | Ethan Lowman <ethan.lowman@datadoghq.com> | Mon Nov 29 11:27:54 2021 -0500 |
| tree | eb21122ec196d1c60201e3a72c7801448f5ec9e7 | |
| parent | b4b4c967e3b724b6a82106a4ebf9cb07bbcd34c0 [diff] |
Idea for PassphraseChanger
This is a Go implementation of The Update Framework (TUF), a framework for securing software update systems.
A TUF repository has the following directory layout:
. ├── keys ├── repository │ └── targets └── staged └── targets
The directories contain the following files:
keys/ - signing keys (optionally encrypted) with filename pattern ROLE.jsonrepository/ - signed metadata filesrepository/targets/ - hashed target filesstaged/ - either signed, unsigned or partially signed metadata filesstaged/targets/ - unhashed target filesgo-tuf provides a CLI for managing a local TUF repository.
go get github.com/theupdateframework/go-tuf/cmd/tuf
tuf init [--consistent-snapshot=false]Initializes a new repository.
This is only required if the repository should not generate consistent snapshots (i.e. by passing --consistent-snapshot=false). If consistent snapshots should be generated, the repository will be implicitly initialized to do so when generating keys.
tuf gen-key [--expires=<days>] <role>Prompts the user for an encryption passphrase (unless the --insecure-plaintext flag is set), then generates a new signing key and writes it to the relevant key file in the keys directory. It also stages the addition of the new key to the root metadata file. Alternatively, passphrases can be set via environment variables in the form of TUF_{{ROLE}}_PASSPHRASE
tuf revoke-key [--expires=<days>] <role> <id>Revoke a signing key
The key will be removed from the root metadata file, but the key will remain in the “keys” directory if present.
tuf add [<path>...]Hashes files in the staged/targets directory at the given path(s), then updates and stages the targets metadata file. Specifying no paths hashes all files in the staged/targets directory.
tuf remove [<path>...]Stages the removal of files with the given path(s) from the targets metadata file (they get removed from the filesystem when the change is committed). Specifying no paths removes all files from the targets metadata file.
tuf snapshot [--expires=<days>]Expects a staged, fully signed targets metadata file and stages an appropriate snapshot metadata file. Optionally one can set number of days after which the snapshot metadata will expire.
tuf timestampStages an appropriate timestamp metadata file. If a snapshot metadata file is staged, it must be fully signed.
tuf sign <metadata>Signs the given role's staged metadata file with all keys present in the keys directory for that role.
tuf commitVerifies that all staged changes contain the correct information and are signed to the correct threshold, then moves the staged files into the repository directory. It also removes any target files which are not in the targets metadata file.
tuf regenerate [--consistent-snapshot=false]Note: Not supported yet
Recreates the targets metadata file based on the files in repository/targets.
tuf cleanRemoves all staged metadata files and targets.
tuf root-keysOutputs a JSON serialized array of root keys to STDOUT. The resulting JSON should be distributed to clients for performing initial updates.
tuf set-threshold <role> <threshold>Sets the role threshold, the required number of keys for signing, to threshold.
tuf change-passphrase <role>Changes the passphrase for given role keys file.
The tuf CLI supports receiving passphrases via environment variables in the form of TUF_{{ROLE}}_PASSPHRASE
For a list of supported commands, run tuf help from the command line.
The following are example workflows for managing a TUF repository with the CLI.
The tree commands do not need to be run, but their output serve as an illustration of what files should exist after performing certain commands.
Although only two machines are referenced (i.e. the “root” and “repo” boxes), the workflows can be trivially extended to many signing machines by copying staged changes and signing on each machine in turn before finally committing.
Some key IDs are truncated for illustrative purposes.
Generate a root key on the root box:
$ tuf gen-key root Enter root keys passphrase: Repeat root keys passphrase: Generated root key with ID 184b133f $ tree . . ├── keys │ └── root.json ├── repository └── staged ├── root.json └── targets
Copy staged/root.json from the root box to the repo box and generate targets, snapshot and timestamp keys:
$ tree . . ├── keys ├── repository └── staged ├── root.json └── targets $ tuf gen-key targets Enter targets keys passphrase: Repeat targets keys passphrase: Generated targets key with ID 8cf4810c $ tuf gen-key snapshot Enter snapshot keys passphrase: Repeat snapshot keys passphrase: Generated snapshot key with ID 3e070e53 $ tuf gen-key timestamp Enter timestamp keys passphrase: Repeat timestamp keys passphrase: Generated timestamp key with ID a3768063 $ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository └── staged ├── root.json └── targets
Copy staged/root.json from the repo box back to the root box and sign it:
$ tree . . ├── keys │ ├── root.json ├── repository └── staged ├── root.json └── targets $ tuf sign root.json Enter root keys passphrase:
The staged root.json can now be copied back to the repo box ready to be committed alongside other metadata files.
Assuming a staged, signed root metadata file and the file to add exists at staged/targets/foo/bar/baz.txt:
$ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository └── staged ├── root.json └── targets └── foo └── bar └── baz.txt $ tuf add foo/bar/baz.txt Enter targets keys passphrase: $ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository └── staged ├── root.json ├── targets │ └── foo │ └── bar │ └── baz.txt └── targets.json $ tuf snapshot Enter snapshot keys passphrase: $ tuf timestamp Enter timestamp keys passphrase: $ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository └── staged ├── root.json ├── snapshot.json ├── targets │ └── foo │ └── bar │ └── baz.txt ├── targets.json └── timestamp.json $ tuf commit $ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged
Assuming the file to remove is at repository/targets/foo/bar/baz.txt:
$ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged $ tuf remove foo/bar/baz.txt Enter targets keys passphrase: $ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged └── targets.json $ tuf snapshot Enter snapshot keys passphrase: $ tuf timestamp Enter timestamp keys passphrase: $ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged ├── snapshot.json ├── targets.json └── timestamp.json $ tuf commit $ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json └── staged
$ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged $ tuf regenerate Enter targets keys passphrase: $ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged └── targets.json $ tuf snapshot Enter snapshot keys passphrase: $ tuf timestamp Enter timestamp keys passphrase: $ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged ├── snapshot.json ├── targets.json └── timestamp.json $ tuf commit $ tree . . ├── keys │ ├── snapshot.json │ ├── targets.json │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged
$ tree . . ├── keys │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged $ tuf timestamp Enter timestamp keys passphrase: $ tree . . ├── keys │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged └── timestamp.json $ tuf commit $ tree . . ├── keys │ └── timestamp.json ├── repository │ ├── root.json │ ├── snapshot.json │ ├── targets │ │ └── foo │ │ └── bar │ │ └── baz.txt │ ├── targets.json │ └── timestamp.json └── staged
For the client package, see https://godoc.org/github.com/theupdateframework/go-tuf/client.
For the client CLI, see https://github.com/theupdateframework/go-tuf/tree/master/cmd/tuf-client.