Elgato_dark/python-tuf
1
0
Fork 0
mirror of https://github.com/theupdateframework/python-tuf synced 2026-05-24 10:08:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #759 from vladimir-v-diaz/revise_CLI.md

Browse source 
Revise CLI.md to address reviewer comments
This commit is contained in:
Vladimir Diaz 2018-06-27 11:48:50 -04:00 committed by GitHub
commit c8433b4834
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 34 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

67
docs/CLI.md
View file

@ -8,7 +8,7 @@ The CLI requires a few dependencies and C extensions that can be installed with
[CLI_EXAMPLES.md](CLI_EXAMPLES.md) covers more complex examples.
----
## Create a repository ##
Create a TUF repository in the current working directory. A cryptographic key
@ -24,7 +24,7 @@ Optionally, the repository can be written to a specified location.
$ repo.py --init --path </path/to/repo_dir>
```
Note: The default top-level key files created with `--init` are saved to disk
The default top-level key files created with `--init` are saved to disk
encrypted, with a default password of 'pw'. Instead of using the default
password, the user can enter one on the command line for each top-level role.
These optional command-line options also work with other CLI actions (e.g.,
@ -35,8 +35,8 @@ $ repo.py --init [--targets_pw, --root_pw, --snapshot_pw, --timestamp_pw]
Create a TUF repository in the current working directory. A cryptographic key
is *not* created nor set for each top-level role.
Create a bare TUF repository in the current working directory. A cryptographic
key is *not* created nor set for each top-level role.
```Bash
$ repo.py --init --bare
```
@ -54,7 +54,6 @@ $ repo.py --init --consistent
## Add a target file ##
Copy a target file to the repo and add it to the Targets metadata (or the
@ -75,9 +74,6 @@ $ repo.py --add <foo.tar.gz> --path </path/to/my_repo>
## Remove a target file ##
Remove a target file from the Targets metadata (or the Targets role specified
@ -106,10 +102,11 @@ $ repo.py --remove "*" --role my_role --sign tufkeystore/my_role_key
Generate a cryptographic key. The generated key can later be used to sign
specific metadata with `--sign`. The supported key types are: `ecdsa`,
`ed25519`, and `rsa`. If a keytype is not given, an Ed25519 key is generated.
Note: If adding a top-level key to a bare repo (i.e., repo.py --init --bare),
the top-level keys should be named "root_key," "targets_key," "snapshot_key,"
"timestamp_key." Additional top-level keys may be named anything, and must be
used with --sign.
If adding a top-level key to a bare repo (i.e., repo.py --init --bare),
the filenames of the top-level keys must be "root_key," "targets_key,"
"snapshot_key," "timestamp_key." The filename can vary for any additional
top-level key.
```Bash
$ repo.py --key
$ repo.py --key <keytype>
@ -131,6 +128,21 @@ Confirm:
## Sign metadata ##
Sign, with the specified key(s), the metadata of the role indicated in --role.
The Snapshot and Timestamp role are also automatically signed, if possible, but
this behavior can be disabled with --no_release.
```Bash
$ repo.py --sign </path/to/key> ... [--role <rolename>, --path </path/to/repo>]
```
For example, to sign the delegated `foo` metadata:
```Bash
$ repo.py --sign /path/to/foo_key --role foo
```
## Trust keys ##
The Root role specifies the trusted keys of the top-level roles, including
@ -148,6 +160,8 @@ $ repo.py --trust --pubkeys tufkeystore/my_key.pub tufkeystore/my_key_too.pub
--role root
```
### Distrust keys ###
Conversely, the Root role can discontinue trust of specified key(s).
@ -159,25 +173,7 @@ $ repo.py --distrust --pubkeys tufkeystore/my_key_too.pub --role root
## Sign metadata ##
Sign, with the specified key(s), the metadata of the role indicated in --role.
The Snapshot and Timestamp role are also automatically signed, if possible, but
this behavior can be disabled with --no_release.
```Bash
$ repo.py --sign </path/to/key> ... [--role <rolename>, --path </path/to/repo>]
```
For example, to sign the delegated `foo` metadata:
```Bash
$ repo.py --sign /path/to/foo_key --role foo
```
Note: In the future, the user might have the option of disabling automatic
signing of Snapshot and Timestamp metadata.
## Delegation ##
## Delegations ##
Delegate trust of target files from the Targets role (or the one specified in
--role) to some other role (--delegatee). --delegatee is trusted to sign for
@ -201,7 +197,7 @@ $ repo.py --delegate "foo*.tgz" --delegatee foo --pubkeys tufkeystore/foo.pub
## Revocation ##
## Revocations ##
Revoke trust of target files from a delegated role (--delegatee). The
"targets" role performs the revocation if --role is not specified. The
@ -232,8 +228,13 @@ $ repo.py --verbose <0-5>
## Clean ##
Remove the files created via `repo.py --init`.
Delete the repo in the current working directory, or the one specified with
`--path`. Specifically, the `tufrepo`, `tufclient`, and `tufkeystore`
directories are deleted.
```Bash
$ repo.py --clean
$ repo.py --clean --path </path/to/dirty/repo>
```
(--clean by itself removes TUF files from the current working directory.)
----