From 007aff70bffac7bc83dde7796199ab51edea83f0 Mon Sep 17 00:00:00 2001 From: Riyaz Faizullabhoy Date: Fri, 25 Aug 2017 11:42:44 -0700 Subject: [PATCH] docs: update docker trust docs with correct tense and formatting Signed-off-by: Riyaz Faizullabhoy --- docs/reference/commandline/trust_inspect.md | 23 +++++++++++++-------- docs/reference/commandline/trust_revoke.md | 11 +++++----- docs/reference/commandline/trust_sign.md | 17 ++++++++------- 3 files changed, 28 insertions(+), 23 deletions(-) diff --git a/docs/reference/commandline/trust_inspect.md b/docs/reference/commandline/trust_inspect.md index addce15f5e..9de9bad9f1 100644 --- a/docs/reference/commandline/trust_inspect.md +++ b/docs/reference/commandline/trust_inspect.md @@ -24,11 +24,11 @@ Display detailed information about keys and signatures ## Description -Docker trust inspect provides detailed information on signed repositories. +`docker trust inspect` provides detailed information on signed repositories. This includes all image tags that are signed, who signed them, and who can sign new tags. -By default, `docker trust inspect` will render results in a table. +By default, `docker trust inspect` renders results in a table. ## Examples @@ -38,6 +38,7 @@ By default, `docker trust inspect` will render results in a table. ```bash $ docker trust inspect alpine:latest + SIGNED TAG DIGEST SIGNERS latest 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe (Repo Admin) @@ -46,11 +47,12 @@ Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce ``` -Note that the `SIGNED TAG` maps to the image tag itself, and associates to given image `DIGEST`. `SIGNERS` lists all entities who have signed. +The `SIGNED TAG` is the signed image tag with a unique content-addressable `DIGEST`. `SIGNERS` lists all entities who have signed. -The administrative keys listed specify the root key of trust, as well as the administrative repository key. +The administrative keys listed specify the root key of trust, as well as the administrative repository key. These keys are responsible for modifying signers, and rotating keys for the signed repository. + +If signers are set up for the repository via other `docker trust` commands, `docker trust inspect` displays them appropriately as a `SIGNER` and specify their `KEYS`: -If signers are set up for the repository via other `docker trust` commands, `docker trust inspect` will display them appropriately as a `SIGNER` and specify their `KEYS`: ```bash $ docker trust inspect my-image:purple SIGNED TAG DIGEST SIGNERS @@ -68,14 +70,16 @@ Repository Key: 27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44 Root Key: 40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f ``` -If the image tag is unsigned or unavailable, `docker trust inspect` will not display any signed tags. -``` +If the image tag is unsigned or unavailable, `docker trust inspect` does not display any signed tags. + +```bash $ docker trust inspect unsigned-img No signatures or cannot access unsigned-img ``` -However, if other tags are signed in the same image repository, `docker trust inspect` will report relevant key information. -``` +However, if other tags are signed in the same image repository, `docker trust inspect` reports relevant key information. + +```bash $ docker trust inspect alpine:unsigned No signatures for alpine:unsigned @@ -108,6 +112,7 @@ Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce ``` Here's an example with signers that are set up by `docker trust` commands: + ```bash $ docker trust inspect my-image SIGNED TAG DIGEST SIGNERS diff --git a/docs/reference/commandline/trust_revoke.md b/docs/reference/commandline/trust_revoke.md index 23c3171ea1..b496b2909f 100644 --- a/docs/reference/commandline/trust_revoke.md +++ b/docs/reference/commandline/trust_revoke.md @@ -23,12 +23,11 @@ Remove trust for an image Options: --help Print usage -y, --yes Answer yes to the removal question (no confirmation) - ``` ## Description -Docker trust revoke removes signatures from tags in signed repositories. +`docker trust revoke` removes signatures from tags in signed repositories. ## Examples @@ -54,7 +53,7 @@ Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` -When alice runs `docker trust revoke` like so: +When `alice`, one of the signers, runs `docker trust revoke`: ```bash $ docker trust revoke example/trust-demo:red @@ -62,7 +61,7 @@ Enter passphrase for delegation key with ID 27d42a8: Successfully deleted signature for example/trust-demo:red ``` -the said tag gets removed from the list of released tags: +After revocation, the tag is removed from the list of released tags: ```bash $ docker trust inspect example/trust-demo @@ -101,7 +100,7 @@ Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` -When alice runs `docker trust revoke` like so: +When `alice`, one of the signers, runs `docker trust revoke`: ```bash $ docker trust revoke example/trust-demo @@ -110,7 +109,7 @@ Enter passphrase for delegation key with ID 27d42a8: Successfully deleted signature for example/trust-demo ``` -the all tags that have alice's signature on them get removed from the list of released tags: +All tags that have `alice`'s signature on them are removed from the list of released tags: ```bash $ docker trust inspect example/trust-demo diff --git a/docs/reference/commandline/trust_sign.md b/docs/reference/commandline/trust_sign.md index c6571ea8e3..dfde693e80 100644 --- a/docs/reference/commandline/trust_sign.md +++ b/docs/reference/commandline/trust_sign.md @@ -24,13 +24,13 @@ Sign an image ## Description -Docker trust sign adds signatures to tags to create signed repositories. +`docker trust sign` adds signatures to tags to create signed repositories. ## Examples ### Sign a tag as a repo admin -For an image like so: +Given an image: ```bash $ docker trust inspect example/trust-demo @@ -42,7 +42,7 @@ Repository Key: 36d4c3601102fa7c5712a343c03b94469e5835fb27c191b529c06fd19c14a942 Root Key: 246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b ``` -We can sign a new tag with `docker trust sign`: +Sign a new tag with `docker trust sign`: ```bash $ docker trust sign example/trust-demo:v2 @@ -60,7 +60,8 @@ Signing and pushing trust metadata Enter passphrase for repository key with ID 36d4c36: Successfully signed "docker.io/example/trust-demo":v2 ``` -`docker trust inspect` should now list the new signature: + +`docker trust inspect` lists the new signature: ```bash $ docker trust inspect example/trust-demo @@ -75,7 +76,7 @@ Root Key: 246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b ### Sign a tag as a signer -For an image like so: +Given an image: ```bash $ docker trust inspect example/trust-demo @@ -94,7 +95,7 @@ Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` -We can sign a new tag with `docker trust sign`: +Sign a new tag with `docker trust sign`: ```bash $ docker trust sign example/trust-demo:v1 @@ -111,7 +112,7 @@ Enter passphrase for delegation key with ID 27d42a8: Successfully signed "docker.io/example/trust-demo":v1 ``` -`docker trust inspect` should now list the new signature: +`docker trust inspect` lists the new signature: ```bash $ docker trust inspect example/trust-demo @@ -131,7 +132,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ## Initialize a new repo and sign a tag -When signing an image on a repo for the first time, `docker trust sign` sets up new keys and then signs the image. +When signing an image on a repo for the first time, `docker trust sign` sets up new keys before signing the image. ```bash $ docker trust inspect example/trust-demo