From 0444dcf2f8754e9648c2d50cc9889bdc3fe5dcde Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 5 Jul 2022 17:02:23 -0700 Subject: [PATCH 1/4] notation login CLI Signed-off-by: Steve Lasker --- specs/notation-cli.md | 250 +++++++++++++++++++++++------------------- 1 file changed, 140 insertions(+), 110 deletions(-) diff --git a/specs/notation-cli.md b/specs/notation-cli.md index 9b5c3706e..c37022b51 100644 --- a/specs/notation-cli.md +++ b/specs/notation-cli.md @@ -4,16 +4,18 @@ The following spec outlines the notation CLI. The CLI commands are what's currently available in [notation v0.7.1-alpha.1](https://github.com/notaryproject/notation/releases/tag/v0.7.1-alpha.1). The CLI experience in alpha.1 does not represent the final user experience, and CLI commands may have breaking changes before RC release as the CLI experience is finalized. ## Table of Contents -- [notation](#notation) -- [sign](#sign): Signs artifacts -- [verify](#verify): Verifies OCI Artifacts -- [push](#push): Push signature to remote -- [pull](#pull): Pull signatures from remote -- [list](#list): List signatures from remote + +- [notation](#notation): command group for signing and verification operations +- [cache](#cache): Manage signature cache - [certificate](#certificate): Manage certificates used for verification - [key](#key): Manage keys used for signing -- [cache](#cache): Manage signature cache +- [list](#list): List signatures from remote +- [login](#login): Provide credentials for authenticated registry operations - [plugin](#plugin): Manage KMS plugins +- [pull](#pull): Pull signatures from remote +- [push](#push): Push signature to remote +- [sign](#sign): Signs artifacts +- [verify](#verify): Verifies OCI Artifacts ## notation @@ -32,15 +34,16 @@ AUTHOR: CNCF Notary Project COMMANDS: - sign Signs artifacts - verify Verifies OCI Artifacts - push Push signature to remote - pull Pull signatures from remote - list, ls List signatures from remote + cache Manage signature cache certificate, cert Manage certificates used for verification key Manage keys used for signing - cache Manage signature cache + list, ls List signatures from remote + login Provide credentials for authenticated registry operations plugin Manage KMS plugins + pull Pull signatures from remote + push Push signature to remote + sign Signs artifacts + verify Verifies OCI Artifacts help, h Shows a list of commands or help for one command GLOBAL OPTIONS: @@ -48,186 +51,213 @@ GLOBAL OPTIONS: --version, -v print the version (default: false) ``` -## sign +## cache ```console - notation sign --help + notation cache --help NAME: - notation sign - Signs artifacts + notation cache - Manage signature cache USAGE: - notation sign [command options] + notation cache command [command options] [arguments...] + +COMMANDS: + list, ls List signatures in cache + prune Prune signature from cache + remove, rm Remove signature from cache + help, h Shows a list of commands or help for one command OPTIONS: - --key value, -k value signing key name - --key-file value signing key file - --cert-file value signing certificate file - --timestamp value, -t value timestamp the signed signature via the remote TSA - --expiry value, -e value expire duration (default: 0s) - --reference value, -r value original reference - --local, -l reference is a local file (default: false) - --output value, -o value write signature to a specific path - --push push after successful signing (default: true) - --push-reference value different remote to store signature - --username value, -u value username for generic remote access [$NOTATION_USERNAME] - --password value, -p value password for generic remote access [$NOTATION_PASSWORD] - --plain-http remote access via plain HTTP (default: false) - --media-type value specify the media type of the manifest read from file or stdin (default: "application/vnd.docker.distribution.manifest.v2+json") - --help, -h show help (default: false) + --help, -h show help (default: false) ``` -## verify +## certificate ```console -notation verify --help +notation certificate --help NAME: - notation verify - Verifies OCI Artifacts + notation certificate - Manage certificates used for verification USAGE: - notation verify [command options] + notation certificate command [command options] [arguments...] + +COMMANDS: + add Add certificate to verification list + list, ls List certificates used for verification + remove, rm Remove certificate from the verification list + generate-test Generates a test RSA key and a corresponding self-signed certificate + help, h Shows a list of commands or help for one command OPTIONS: - --signature value, -s value, -f value signature files (accepts multiple inputs) - --cert value, -c value certificate names for verification (accepts multiple inputs) - --cert-file value certificate files for verification (accepts multiple inputs) - --pull pull remote signatures before verification (default: true) - --local, -l reference is a local file (default: false) - --username value, -u value username for generic remote access [$NOTATION_USERNAME] - --password value, -p value password for generic remote access [$NOTATION_PASSWORD] - --plain-http remote access via plain HTTP (default: false) - --media-type value specify the media type of the manifest read from file or stdin (default: "application/vnd.docker.distribution.manifest.v2+json") - --help, -h show help (default: false) + --help, -h show help (default: false) ``` -## push +## key ```console -notation push --help +notation key --help NAME: - notation push - Push signature to remote + notation key - Manage keys used for signing USAGE: - notation push [command options] + notation key command [command options] [arguments...] + +COMMANDS: + add Add key to signing key list + update, set Update key in signing key list + list, ls List keys used for signing + remove, rm Remove key from signing key list + help, h Shows a list of commands or help for one command OPTIONS: - --signature value, -s value, -f value signature files (accepts multiple inputs) - --username value, -u value username for generic remote access [$NOTATION_USERNAME] - --password value, -p value password for generic remote access [$NOTATION_PASSWORD] - --plain-http remote access via plain HTTP (default: false) - --help, -h show help (default: false) + --help, -h show help (default: false) ``` -## pull +## list ```console -notation pull --help +notation list --help NAME: - notation pull - Pull signatures from remote + notation list - List signatures from remote USAGE: - notation pull [command options] + notation list [command options] OPTIONS: - --strict pull the signature without lookup the manifest (default: false) - --output value, -o value write signature to a specific path --username value, -u value username for generic remote access [$NOTATION_USERNAME] --password value, -p value password for generic remote access [$NOTATION_PASSWORD] --plain-http remote access via plain HTTP (default: false) --help, -h show help (default: false) ``` -## list +## login ```console -notation list --help +notation login --help NAME: - notation list - List signatures from remote + notation login - Provides credentials for authenticated registry operations USAGE: - notation list [command options] + notation login [options] [server] OPTIONS: - --username value, -u value username for generic remote access [$NOTATION_USERNAME] - --password value, -p value password for generic remote access [$NOTATION_PASSWORD] - --plain-http remote access via plain HTTP (default: false) - --help, -h show help (default: false) + --username value, -u value Username for registry operations + --password value, -p value Password for registry operations + --help, -h Show help (default: false) + +POSITIONAL + The registry URL for authentication + +GLOBAL ARGUMENTS + --plain-http Registry access via plain HTTP (default: false) + +EXAMPLES + +notation login -u -p registry.example.com ``` -## certificate +## plugin ```console -notation certificate --help +notation plugin --help NAME: - notation certificate - Manage certificates used for verification + notation plugin - Manage plugins USAGE: - notation certificate command [command options] [arguments...] + notation plugin command [command options] [arguments...] COMMANDS: - add Add certificate to verification list - list, ls List certificates used for verification - remove, rm Remove certificate from the verification list - generate-test Generates a test RSA key and a corresponding self-signed certificate - help, h Shows a list of commands or help for one command + list List registered plugins + help, h Shows a list of commands or help for one command OPTIONS: --help, -h show help (default: false) ``` -## key +## pull ```console -notation key --help +notation pull --help NAME: - notation key - Manage keys used for signing + notation pull - Pull signatures from remote USAGE: - notation key command [command options] [arguments...] - -COMMANDS: - add Add key to signing key list - update, set Update key in signing key list - list, ls List keys used for signing - remove, rm Remove key from signing key list - help, h Shows a list of commands or help for one command + notation pull [command options] OPTIONS: - --help, -h show help (default: false) + --strict pull the signature without lookup the manifest (default: false) + --output value, -o value write signature to a specific path + --username value, -u value username for generic remote access [$NOTATION_USERNAME] + --password value, -p value password for generic remote access [$NOTATION_PASSWORD] + --plain-http remote access via plain HTTP (default: false) + --help, -h show help (default: false) ``` -## cache + +## push ```console - notation cache --help +notation push --help NAME: - notation cache - Manage signature cache + notation push - Push signature to remote USAGE: - notation cache command [command options] [arguments...] - -COMMANDS: - list, ls List signatures in cache - prune Prune signature from cache - remove, rm Remove signature from cache - help, h Shows a list of commands or help for one command + notation push [command options] OPTIONS: - --help, -h show help (default: false) + --signature value, -s value, -f value signature files (accepts multiple inputs) + --username value, -u value username for generic remote access [$NOTATION_USERNAME] + --password value, -p value password for generic remote access [$NOTATION_PASSWORD] + --plain-http remote access via plain HTTP (default: false) + --help, -h show help (default: false) ``` -## plugin +## sign ```console -notation plugin --help + notation sign --help NAME: - notation plugin - Manage plugins + notation sign - Signs artifacts USAGE: - notation plugin command [command options] [arguments...] + notation sign [command options] -COMMANDS: - list List registered plugins - help, h Shows a list of commands or help for one command +OPTIONS: + --key value, -k value signing key name + --key-file value signing key file + --cert-file value signing certificate file + --timestamp value, -t value timestamp the signed signature via the remote TSA + --expiry value, -e value expire duration (default: 0s) + --reference value, -r value original reference + --local, -l reference is a local file (default: false) + --output value, -o value write signature to a specific path + --push push after successful signing (default: true) + --push-reference value different remote to store signature + --username value, -u value username for generic remote access [$NOTATION_USERNAME] + --password value, -p value password for generic remote access [$NOTATION_PASSWORD] + --plain-http remote access via plain HTTP (default: false) + --media-type value specify the media type of the manifest read from file or stdin (default: "application/vnd.docker.distribution.manifest.v2+json") + --help, -h show help (default: false) +``` + +## verify + +```console +notation verify --help +NAME: + notation verify - Verifies OCI Artifacts + +USAGE: + notation verify [command options] OPTIONS: - --help, -h show help (default: false) -``` \ No newline at end of file + --signature value, -s value, -f value signature files (accepts multiple inputs) + --cert value, -c value certificate names for verification (accepts multiple inputs) + --cert-file value certificate files for verification (accepts multiple inputs) + --pull pull remote signatures before verification (default: true) + --local, -l reference is a local file (default: false) + --username value, -u value username for generic remote access [$NOTATION_USERNAME] + --password value, -p value password for generic remote access [$NOTATION_PASSWORD] + --plain-http remote access via plain HTTP (default: false) + --media-type value specify the media type of the manifest read from file or stdin (default: "application/vnd.docker.distribution.manifest.v2+json") + --help, -h show help (default: false) +``` From 0c16151d5f7ad9909a9146eb674b318426033c4f Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 5 Jul 2022 17:27:23 -0700 Subject: [PATCH 2/4] add accidentlal removal of list back Signed-off-by: Steve Lasker --- specs/notation-cli.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/specs/notation-cli.md b/specs/notation-cli.md index d13547272..f5090cc2f 100644 --- a/specs/notation-cli.md +++ b/specs/notation-cli.md @@ -37,7 +37,8 @@ COMMANDS: certificate, cert Manage certificates used for verification key Manage keys used for signing list, ls List signatures from remote - login Provide credentials for authenticated registry operations plugin Manage KMS plugins + login Provide credentials for authenticated registry operations + plugin Manage KMS plugins pull Pull signatures from remote push Push signature to remote sign Signs artifacts @@ -111,6 +112,23 @@ OPTIONS: --help, -h show help (default: false) ``` +## list + +```console +notation list --help +NAME: + notation list - List signatures from remote + +USAGE: + notation list [command options] + +OPTIONS: + --username value, -u value username for generic remote access [$NOTATION_USERNAME] + --password value, -p value password for generic remote access [$NOTATION_PASSWORD] + --plain-http remote access via plain HTTP (default: false) + --help, -h show help (default: false) +``` + ## login ```console From 3a888a37c9de565f2c1bb64d5b27ac8aceceb851 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 5 Jul 2022 17:28:17 -0700 Subject: [PATCH 3/4] add accidentlal removal of list back Signed-off-by: Steve Lasker --- specs/notation-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/notation-cli.md b/specs/notation-cli.md index f5090cc2f..21f47b777 100644 --- a/specs/notation-cli.md +++ b/specs/notation-cli.md @@ -8,8 +8,8 @@ The CLI commands are what's currently available in [notation v0.7.1-alpha.1](htt - [cache](#cache): Manage signature cache - [certificate](#certificate): Manage certificates used for verification - [key](#key): Manage keys used for signing -- [login](#login): Provide credentials for authenticated registry operations - [list](#list): List signatures from remote +- [login](#login): Provide credentials for authenticated registry operations - [plugin](#plugin): Manage KMS plugins - [pull](#pull): Pull signatures from remote - [push](#push): Push signature to remote From 317dc3017f91acf462489e46d975f52d6462e2a1 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Mon, 11 Jul 2022 10:49:55 -0700 Subject: [PATCH 4/4] Update to use environment variables and remove -u/-p on all other commands Signed-off-by: Steve Lasker --- specs/notation-cli.md | 31 ++++++++++--------------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/specs/notation-cli.md b/specs/notation-cli.md index 21f47b777..502e052e1 100644 --- a/specs/notation-cli.md +++ b/specs/notation-cli.md @@ -123,9 +123,6 @@ USAGE: notation list [command options] OPTIONS: - --username value, -u value username for generic remote access [$NOTATION_USERNAME] - --password value, -p value password for generic remote access [$NOTATION_PASSWORD] - --plain-http remote access via plain HTTP (default: false) --help, -h show help (default: false) ``` @@ -140,8 +137,9 @@ USAGE: notation login [options] [server] OPTIONS: - --username value, -u value Username for registry operations - --password value, -p value Password for registry operations + --username value, -u value Username for registry operations [$NOTATION_USERNAME] + --password value, -p value Password for registry operations [$NOTATION_PASSWORD] + --password-stdin Take the password from stdin --help, -h Show help (default: false) POSITIONAL @@ -151,8 +149,11 @@ GLOBAL ARGUMENTS --plain-http Registry access via plain HTTP (default: false) EXAMPLES - +# Login with provided username and password notation login -u -p registry.example.com + +# Login using $NOTATION_USERNAME $NOTATION_PASSWORD variables +notation login registry.example.com ``` ## plugin @@ -184,12 +185,9 @@ USAGE: notation pull [command options] OPTIONS: - --strict pull the signature without lookup the manifest (default: false) - --output value, -o value write signature to a specific path - --username value, -u value username for generic remote access [$NOTATION_USERNAME] - --password value, -p value password for generic remote access [$NOTATION_PASSWORD] - --plain-http remote access via plain HTTP (default: false) - --help, -h show help (default: false) + --strict Pull the signature without lookup the manifest (default: false) + --output value, -o value Write signature to a specific path + --help, -h Show help (default: false) ``` ## push @@ -204,9 +202,6 @@ USAGE: OPTIONS: --signature value, -s value, -f value signature files (accepts multiple inputs) - --username value, -u value username for generic remote access [$NOTATION_USERNAME] - --password value, -p value password for generic remote access [$NOTATION_PASSWORD] - --plain-http remote access via plain HTTP (default: false) --help, -h show help (default: false) ``` @@ -231,9 +226,6 @@ OPTIONS: --output value, -o value write signature to a specific path --push push after successful signing (default: true) --push-reference value different remote to store signature - --username value, -u value username for generic remote access [$NOTATION_USERNAME] - --password value, -p value password for generic remote access [$NOTATION_PASSWORD] - --plain-http remote access via plain HTTP (default: false) --media-type value specify the media type of the manifest read from file or stdin (default: "application/vnd.docker.distribution.manifest.v2+json") --help, -h show help (default: false) ``` @@ -254,9 +246,6 @@ OPTIONS: --cert-file value certificate files for verification (accepts multiple inputs) --pull pull remote signatures before verification (default: true) --local, -l reference is a local file (default: false) - --username value, -u value username for generic remote access [$NOTATION_USERNAME] - --password value, -p value password for generic remote access [$NOTATION_PASSWORD] - --plain-http remote access via plain HTTP (default: false) --media-type value specify the media type of the manifest read from file or stdin (default: "application/vnd.docker.distribution.manifest.v2+json") --help, -h show help (default: false) ```