doc: update notation sign and verify spec for metadata #498

byronchien · 2023-01-03T22:04:55Z

Spec update to support notaryproject/roadmap#67

notation sign:

user will be able to specify additional key value pairs with the --user-metadata flag (-um short) that will be signed as part of the payload.

notation verify:

user will be able to specify additional key value pairs with the --user-metadata flag (-um short) that must be present in the signature to pass verification.
user will be able to configure output format as either plaintext (default) or json with the --output flag (-o short)

Signed-off-by: Byron Chien <chienb@amazon.com>

specs/commandline/sign.md

specs/commandline/verify.md

Signed-off-by: Byron Chien <chienb@amazon.com>

codecov-commenter · 2023-01-04T01:46:14Z

Codecov Report

Merging #498 (765ca1d) into main (f83a48b) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #498   +/-   ##
=======================================
  Coverage   29.57%   29.57%           
=======================================
  Files          26       26           
  Lines        1515     1515           
=======================================
  Hits          448      448           
  Misses       1050     1050           
  Partials       17       17

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

yizha1

Thanks @byronchien for the contribution. I have provided my comments.

specs/commandline/verify.md

specs/commandline/sign.md

specs/commandline/verify.md

specs/commandline/sign.md

specs/commandline/verify.md

Signed-off-by: Byron Chien <chienb@amazon.com>

yizha1

LGTM with some comments

yizha1 · 2023-01-06T08:50:03Z

specs/commandline/verify.md

+An example of output messages for an unsuccessful verification:
+
+```text
+Error: signature verification failed for all the signatures associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9


If the verification failure is due to metadata, there should be error log like you shared under the debug logging.

"Error: specified metadata is not present in the signature."

Signed-off-by: Byron Chien <chienb@amazon.com>

priteshbandi · 2023-01-12T07:57:01Z

specs/commandline/verify.md

@@ -16,6 +16,17 @@ Warning: The resolved digest may not point to the same signed artifact, since ta
 Successfully verified signature for <registry>/<repository>@<digest>
 ```

+The signed descriptor may have user defined metadata attached. If the signature for the OCI artifact contains any metadata, the output message is as follows:


Suggested change

The signed descriptor may have user defined metadata attached. If the signature for the OCI artifact contains any metadata, the output message is as follows:

A signature can have user defined metadata. If the signature for the OCI artifact contains any metadata, the output message is as follows:

priteshbandi · 2023-01-12T07:57:39Z

specs/commandline/verify.md

+```text
+Successfully verified signature for <registry>/<repository>@<digest>
+
+The artifact is signed with the following user metadata.


Suggested change

The artifact is signed with the following user metadata.

The artifact was signed with the following user metadata:

priteshbandi · 2023-01-12T08:26:39Z

specs/commandline/verify.md

+An example of output messages for an unsuccessful verification with verbose logging enabled:
+
+```text
+INFO Checking whether signature verification should be skipped or not
+INFO Check over. Trust policy is not configured to skip signature verification
+INFO Processing signature with digest: sha256:dbb22c0686b714ccbb53e4579771ee0f9ab9d37cd77cadb767549322742979f3
+INFO User Metadata flag is present. Checking signature metadata for specified values.
+Error: unable to find specified metadata in any signatures associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+Error: signature verification failed for all the signatures associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+```
+
+An example of output messages for an unsuccessful verification with debug logging enabled:
+
+```text
+...
+INFO User Metadata flag is present. Checking signature metadata for specified values.
+DEBU[2023-01-05T11:35:07-08:00] Verifying that metadata { "io.wabbit-networks.buildId":"123" } is present in signature metadata.
+DEBU[2023-01-05T11:35:07-08:00] Signature metadata: { "io.wabbit-networks.buildId":"321" }
+DEBU[2023-01-05T11:35:07-08:00] Error: specified metadata is not present in the signature.
+Error: unable to find specified metadata in any signatures associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+Error: signature verification failed for all the signatures associated with localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+```


I wouldn't add verbose and debug usecases in the spec as this can change during implementation.

ok, will remove, also matches existing spec that doesn't have verbose/debug examples

shizhMSFT

LGTM

Signed-off-by: Byron Chien <chienb@amazon.com>

priteshbandi

LGTM

…#498) Spec update to support notaryproject/roadmap#67 `notation sign`: - user will be able to specify additional key value pairs with the `--user-metadata` flag (`-um` short) that will be signed as part of the payload. `notation verify`: - user will be able to specify additional key value pairs with the `--user-metadata` flag (`-um` short) that must be present in the signature to pass verification. Signed-off-by: Byron Chien <chienb@amazon.com>

Adds support for signed user metadata in `notation sign` and `notation verify`. [Relevant spec](notaryproject/notation#498) example sign usage: notation % notation sign $IMAGE --user-metadata io.wabbit-networks.buildId=123 --user-metadata io.wabbit-networks.buildTime=123 Successfully signed localhost:5000/net-monitor@sha256:5a07385af4e6b6af81b0ebfd435aedccdfa3507f0609c658209e1aba57159b2b example verification: ``` notation % notation verify $IMAGE --user-metadata io.wabbit-networks.buildTime=123 Successfully verified signature for localhost:5000/net-monitor@sha256:5a07385af4e6b6af81b0ebfd435aedccdfa3507f0609c658209e1aba57159b2b The artifact was signed with the following user metadata. KEY VALUE io.wabbit-networks.buildTime 123 io.wabbit-networks.buildId 123 ``` Signed-off-by: Byron Chien <chienb@amazon.com>

…y cmds (#507) Adds support for signed user metadata in `notation sign` and `notation verify`. [Relevant spec](#498) example sign usage: chienb@a07817b52895 notation % notation sign $IMAGE --user-metadata io.wabbit-networks.buildId=123 --user-metadata io.wabbit-networks.buildTime=123 Successfully signed localhost:5000/net-monitor@sha256:5a07385af4e6b6af81b0ebfd435aedccdfa3507f0609c658209e1aba57159b2b --------------- example verification: chienb@a07817b52895 notation % notation verify $IMAGE --user-metadata io.wabbit-networks.buildTime=123 Resolved artifact tag `v1` to digest `sha256:5a07385af4e6b6af81b0ebfd435aedccdfa3507f0609c658209e1aba57159b2b` 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:5a07385af4e6b6af81b0ebfd435aedccdfa3507f0609c658209e1aba57159b2b The artifact was signed with the following user metadata. KEY VALUE io.wabbit-networks.buildTime 123 io.wabbit-networks.buildId 123 ----- Signed-off-by: Byron Chien <chienb@amazon.com>

allows json output for `notation verify`. Fixes notaryproject/roadmap#67 and #498 chienb@a07817b52895 notation % ./bin/notation verify $IMAGE --output json { "reference": "localhost:5000/net-monitor@sha256:5a07385af4e6b6af81b0ebfd435aedccdfa3507f0609c658209e1aba57159b2b", "userMetadata": { "foo": "bar" }, "result": "Success" } Signed-off-by: Byron Chien <chienb@amazon.com>

Update notation sign and verify spec for metadata

9eebe91

Signed-off-by: Byron Chien <chienb@amazon.com>

byronchien force-pushed the attestations branch from 4405424 to 9eebe91 Compare January 3, 2023 23:17

byronchien changed the title ~~Upate notation sign and verify spec for metadata~~ Update notation sign and verify spec for metadata Jan 3, 2023

priteshbandi reviewed Jan 3, 2023

View reviewed changes

Removes restrictions, clarifies flag description, reorders examples

c7c5128

Signed-off-by: Byron Chien <chienb@amazon.com>

byronchien force-pushed the attestations branch from 1f4bcf5 to c7c5128 Compare January 4, 2023 00:24

priteshbandi requested review from shizhMSFT, yizha1 and FeynmanZhou January 4, 2023 01:43

shizhMSFT changed the title ~~Update notation sign and verify spec for metadata~~ doc: update notation sign and verify spec for metadata Jan 4, 2023

yizha1 reviewed Jan 4, 2023

View reviewed changes

shizhMSFT reviewed Jan 5, 2023

View reviewed changes

Adds additional output examples and updates short flag

e205408

Signed-off-by: Byron Chien <chienb@amazon.com>

yizha1 approved these changes Jan 6, 2023

View reviewed changes

Adds an error message for metadata failure

765ca1d

Signed-off-by: Byron Chien <chienb@amazon.com>

priteshbandi reviewed Jan 12, 2023

View reviewed changes

shizhMSFT approved these changes Jan 12, 2023

View reviewed changes

Update for PR suggestions

38d9917

Signed-off-by: Byron Chien <chienb@amazon.com>

priteshbandi reviewed Jan 12, 2023

View reviewed changes

priteshbandi approved these changes Jan 12, 2023

View reviewed changes

priteshbandi merged commit 6fb9eef into notaryproject:main Jan 12, 2023

This was referenced Jan 13, 2023

feat: add support for signed user metadata notaryproject/notation-go#242

Merged

feat: add support for signed user metadata in notation sign and verify cmds #507

Merged

byronchien mentioned this pull request Feb 7, 2023

feat: add support for json output for notation verify #527

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: update notation sign and verify spec for metadata #498

doc: update notation sign and verify spec for metadata #498

byronchien commented Jan 3, 2023

codecov-commenter commented Jan 4, 2023 •

edited

Loading

yizha1 left a comment

yizha1 left a comment

yizha1 Jan 6, 2023

priteshbandi Jan 12, 2023

priteshbandi Jan 12, 2023

priteshbandi Jan 12, 2023

byronchien Jan 12, 2023

shizhMSFT left a comment

priteshbandi left a comment

	The signed descriptor may have user defined metadata attached. If the signature for the OCI artifact contains any metadata, the output message is as follows:
	A signature can have user defined metadata. If the signature for the OCI artifact contains any metadata, the output message is as follows:

	The artifact is signed with the following user metadata.
	The artifact was signed with the following user metadata:

doc: update notation sign and verify spec for metadata #498

doc: update notation sign and verify spec for metadata #498

Conversation

byronchien commented Jan 3, 2023

codecov-commenter commented Jan 4, 2023 • edited Loading

Codecov Report

yizha1 left a comment

Choose a reason for hiding this comment

yizha1 left a comment

Choose a reason for hiding this comment

yizha1 Jan 6, 2023

Choose a reason for hiding this comment

priteshbandi Jan 12, 2023

Choose a reason for hiding this comment

priteshbandi Jan 12, 2023

Choose a reason for hiding this comment

priteshbandi Jan 12, 2023

Choose a reason for hiding this comment

byronchien Jan 12, 2023

Choose a reason for hiding this comment

shizhMSFT left a comment

Choose a reason for hiding this comment

priteshbandi left a comment

Choose a reason for hiding this comment

codecov-commenter commented Jan 4, 2023 •

edited

Loading