Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 5 commits into from
Jan 12, 2023
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9eebe91
Update notation sign and verify spec for metadata
Jan 3, 2023
c7c5128
Removes restrictions, clarifies flag description, reorders examples
byronchien Jan 4, 2023
e205408
Adds additional output examples and updates short flag
Jan 5, 2023
765ca1d
Adds an error message for metadata failure
Jan 6, 2023
38d9917
Update for PR suggestions
Jan 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 22 additions & 8 deletions specs/commandline/sign.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,15 @@ Usage:
notation sign [flags] <reference>

Flags:
-e, --expiry duration optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m
-h, --help help for sign
-k, --key string signing key name, for a key previously added to notation's key list.
-p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified)
--plain-http registry access via plain HTTP
--plugin-config strings {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values
--signature-format string signature envelope format, options: 'jws', 'cose' (default "jws")
-u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified)
-e, --expiry duration optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m
-h, --help help for sign
-k, --key string signing key name, for a key previously added to notation's key list.
-p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified)
--plain-http registry access via plain HTTP
--plugin-config strings {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values
--signature-format string signature envelope format, options: 'jws', 'cose' (default "jws")
-u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified)
-m, --user-metadata strings {key}={value} pairs that are added to the signature payload
```

## Usage
Expand Down Expand Up @@ -82,6 +83,19 @@ notation sign --signature-format cose <registry>/<repository>@<digest>
notation sign <registry>/<repository>@<digest>
```

### Sign an OCI Artifact with user metadata

```shell
# Prerequisites:
# A default signing key is configured using CLI "notation key"

# sign an artifact stored in a registry and add user-metadata io.wabbit-networks.buildId=123 to the payload
notation sign --user-metadata io.wabbit-networks.buildId=123 <registry>/<repository>@<digest>

# sign an artifact stored in a registry and add user-metadata io.wabbit-networks.buildId=123 and io.wabbit-networks.buildTime=1672944615 to the payload
notation sign --user-metadata io.wabbit-networks.buildId=123 --user-metadata io.wabbit-networks.buildTime=1672944615 <registry>/<repository>@<digest>
```

### Sign an OCI artifact stored in a registry and specify the signature expiry duration, for example 24 hours

```shell
Expand Down
51 changes: 44 additions & 7 deletions specs/commandline/verify.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
```

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

```text
Successfully verified signature for <registry>/<repository>@<digest>

The artifact was signed with the following user metadata.

KEY VALUE
<key> <value>
```

## Outline

```text
Expand All @@ -25,11 +36,12 @@ Usage:
notation verify [flags] <reference>

Flags:
-h, --help help for verify
-p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified)
--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)
-h, --help help for verify
-p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified)
--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)
-m, --user-metadata strings user defined {key}={value} pairs that must be present in the signature for successful verification if provided
```

## Usage
Expand Down Expand Up @@ -113,13 +125,38 @@ 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 with user metadata

Use the `--user-metadata` flag to verify that provided key-value pairs are present in the payload of the valid signature.

```shell
# Verify signatures on the supplied OCI artifact identified by the digest and verify that io.wabbit-networks.buildId=123 is present in the signed payload
notation verify --user-metadata io.wabbit-networks.buildId=123 localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
```

An example of output messages for a successful verification:

```text
Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

The artifact is signed with the following user metadata.

KEY VALUE
io.wabbit-networks.buildId 123
```

An example of output messages for an unsuccessful verification:

```text
Error: signature verification failed: unable to find specified metadata in any signatures
```

### Verify signatures on an OCI artifact identified by a tag

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
```
Expand All @@ -130,4 +167,4 @@ An example of output messages for a successful verification:
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
```
```