From c7c512811e57a741b9eeb312f03fa7644a7d5048 Mon Sep 17 00:00:00 2001 From: byronchien Date: Tue, 3 Jan 2023 16:15:21 -0800 Subject: [PATCH] Removes restrictions, clarifies flag description, reorders examples Signed-off-by: Byron Chien --- specs/commandline/sign.md | 5 ----- specs/commandline/verify.md | 42 ++++++++++++++++--------------------- 2 files changed, 18 insertions(+), 29 deletions(-) diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md index 7cc5c0a45..8a0da7718 100644 --- a/specs/commandline/sign.md +++ b/specs/commandline/sign.md @@ -40,11 +40,6 @@ Flags: -um, --user-metadata strings {key}={value} pairs that are added to the signature ``` -### User Metadata Restrictions -- `notation sign` must fail if metadata keys or values are not strings -- `notation sign` must fail if duplicate metadata keys are provided -- `notation sign` must fail if metadata keys conflict with reserved Notary or OCI keys - ## Usage ### Sign an OCI artifact diff --git a/specs/commandline/verify.md b/specs/commandline/verify.md index a3d1fa5dd..b069066d3 100644 --- a/specs/commandline/verify.md +++ b/specs/commandline/verify.md @@ -40,7 +40,7 @@ Flags: --plain-http registry access via plain HTTP --plugin-config strings {key}={value} pairs that are passed as it is to a plugin, if the verification is associated with a verification plugin, refer plugin documentation to set appropriate values -u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified) - -um, --user-metadata strings {key}={value} pairs that must be present in the signature for successful verification if provided + -um, --user-metadata strings user defined {key}={value} pairs that must be present in the signature for successful verification if provided ``` ## Usage @@ -124,54 +124,48 @@ An example of output messages for a successful verification: Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` -### Verify signatures on an OCI artifact identified by a tag +### Verify signatures on an OCI artifact with user metadata -A tag is resolved to a digest first before verification. +Use the `--user-metadata` flag to verify that provided key-value pairs are present in the payload of the valid signature. ```shell -# Prerequisites: Signatures are stored in a registry referencing the signed OCI artifact - -# Verify signatures on an OCI artifact identified by the tag -notation verify localhost:5000/net-monitor:v1 +# Verify signatures on the supplied OCI artifact identified by the digest and verify that io.wabbit-networks.data=foo is present in the signed payload +notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 --user-metadata io.wabbit-networks.data=foo ``` An example of output messages for a successful verification: ```text -Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verification. -Warning: The resolved digest may not point to the same signed artifact, since tags are mutable. Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + +User Metadata: +- io.wabbit-networks.data : foo ``` -### Verify signatures on an OCI artifact with user metadata +### Verify signatures on an OCI artifact and format output as json -Use the `--user-metadata` flag to verify that provided key-value pairs are present in the payload of the valid signature. +Use the `--output` flag to configure the format of signature information returned on successful verification. ```shell -# Prerequisites: Signatures are stored in a registry referencing the signed OCI artifact -# Verify signatures on an OCI artifact identified by the tag and verify that io.wabbit-networks.data=foo is present in the signed payload -notation verify localhost:5000/net-monitor:v1 --user-metadata io.wabbit-networks.data=foo + +# Verify signatures on the supplied OCI artifact identified by the digest and output result as json +notation verify localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 --output json ``` An example of output messages for a successful verification: ```text -Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verification. -Warning: The resolved digest may not point to the same signed artifact, since tags are mutable. -Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 - -User Metadata: -- io.wabbit-networks.data : foo +{"reference":"localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9","outcome":"Success","signatures":[{"digest":"sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333","userMetadata":{"io.wabbit-networks.data":"foo"}}]} ``` -### Verify signatures on an OCI artifact and format output as json +### Verify signatures on an OCI artifact identified by a tag -Use the `--output` flag to configure the format of signature information returned on successful verification. +A tag is resolved to a digest first before verification. ```shell # Prerequisites: Signatures are stored in a registry referencing the signed OCI artifact # Verify signatures on an OCI artifact identified by the tag -notation verify localhost:5000/net-monitor:v1 --output json +notation verify localhost:5000/net-monitor:v1 ``` An example of output messages for a successful verification: @@ -179,5 +173,5 @@ An example of output messages for a successful verification: ```text Resolved artifact tag `v1` to digest `sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` before verification. Warning: The resolved digest may not point to the same signed artifact, since tags are mutable. -{"reference":"localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9","outcome":"Success","signatures":[{"digest":"sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333","userMetadata":{"io.wabbit-networks.data":"foo"}}]} +Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ``` \ No newline at end of file