-
Notifications
You must be signed in to change notification settings - Fork 84
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.
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
spec: update cli sign spec for tag to digest translation #439
Merged
Merged
Changes from 25 commits
Commits
Show all changes
29 commits
Select commit
Hold shift + click to select a range
df1e729
Build:Bump dependencies
yizha1 bcc2ea4
Build: Bump dependencies
yizha1 f72b2a6
Build: Bump dependencies
yizha1 1950096
Merge branch 'notaryproject:main' into main
yizha1 4b76dfc
Merge branch 'notaryproject:main' into main
yizha1 c0f2d12
Merge branch 'notaryproject:main' into main
yizha1 8735263
Merge branch 'notaryproject:main' into main
yizha1 7ddfebd
Merge branch 'notaryproject:main' into main
yizha1 75dd7aa
Merge branch 'notaryproject:main' into main
yizha1 94ed3c4
Merge branch 'notaryproject:main' into main
yizha1 0b37d70
Merge branch 'notaryproject:main' into main
yizha1 0a11b6d
Merge branch 'main' of https://github.com/yizha1/notation into main
yizha1 ac23127
Merge branch 'main' of https://github.com/yizha1/notation into main
yizha1 b91b4cb
Merge branch 'main' of https://github.com/yizha1/notation into main
yizha1 f817dfd
Merge branch 'main' of https://github.com/yizha1/notation into main
yizha1 3c0df15
Merge branch 'main' of https://github.com/yizha1/notation into main
yizha1 226c245
Merge branch 'main' of https://github.com/yizha1/notation into main
yizha1 cc4e2a9
Merge branch 'main' of https://github.com/yizha1/notation into main
yizha1 1b1afbb
Merge branch 'main' of https://github.com/yizha1/notation into main
yizha1 4754adb
spec: update sign cli spec for tag to digest
yizha1 ec8782b
spec: update digest value
yizha1 783c343
spec: update debug description
yizha1 98c9503
spec: update according to review comments
yizha1 3d5a887
spec: remove the changes for debug option
yizha1 e52a8bf
spec: update according to comments
yizha1 997c8dc
update typos
yizha1 8809288
update per comments
yizha1 5b18a55
update according to comments
yizha1 5b9e582
update according to comments
yizha1 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -4,7 +4,21 @@ | |
|
||
Use `notation sign` to sign artifacts. | ||
|
||
Signs an OCI artifact that is stored in a registry. Upon successful signing, the generated signature is pushed to the registry with the digest of the OCI artifact returned. | ||
Signs an OCI artifact stored in the registry. Always sign artifact using digest(`@sha256:...`) rather than a tag(`:latest`) because tags are mutable and a tag reference can point to a different artifact than the one signed. If a tag is used, notation resolves the tag to the `digest` before signing. | ||
|
||
Upon successful signing, the generated signature is pushed to the registry and associated with the signed OCI artifact. The output message is printed out as following: | ||
|
||
```text | ||
Successfully signed <registry>/<repository>@<digest>. | ||
``` | ||
|
||
If a `tag` is used to identify the OCI artifact, the output message is as following: | ||
|
||
```test | ||
Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag(`:latest`) because tags are mutable and a tag reference can point to a different artifact than the one signed. | ||
Resolving artifact tag '<tag>' to digest '<digest>' before signing. | ||
Successfully signed <registry>/<repository>@<digest> | ||
``` | ||
|
||
## Outline | ||
|
||
|
@@ -27,58 +41,78 @@ Flags: | |
|
||
## Usage | ||
|
||
### Sign a container image | ||
### Sign an OCI artifact | ||
|
||
```shell | ||
# Add a key which uses a local private key and certificate, and make it a default signing key | ||
notation key add --default --name <key_name> <key_path> <cert_path> | ||
|
||
# Or change the default signing key to an existing signing key | ||
notation key update --default <key_name> | ||
# Prerequisites: | ||
# - A signing plugin is installed. See plugin documentation (https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md) for more details. | ||
yizha1 marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Instead of the main branch, should we use a tag version for the URL? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can we update it later once we have cut a version for notaryproject? |
||
# - Configure the signing plugin as instructed by plugin vendor. | ||
|
||
# Sign a container image using the default signing key | ||
notation sign <registry>/<repository>:<tag> | ||
# Add a default signing key referencing the remote key identifier, and the plugin associated with it. | ||
notation key add --default --name <key_name> --plugin <plugin_name> --id <remote_key_id> | ||
|
||
# Or using container image digests instead of tags. A container image digest uniquely and immutably identifies a container image. | ||
# sign an artifact stored in a registry | ||
notation sign <registry>/<repository>@<digest> | ||
``` | ||
|
||
### Sign a container image using a remote key | ||
An example for a successful signing: | ||
|
||
```shell | ||
yizha1 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
# Prerequisites: | ||
# - A compliant signing plugin is installed in notation. See notation plugin documentation (https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md) for more details. | ||
# - User creates keys and certificates in a 3rd party key provider (e.g. key vault, key management service). The signing plugin installed in previous step must support generating signatures using this key provider. | ||
$ notation sign localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 | ||
Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9. | ||
``` | ||
|
||
# Add a default signing key referencing the key identifier for the remote key, and the plugin associated with it. | ||
notation key add --default --name <key_name> --plugin <plugin_name> --id <remote_key_id> | ||
### Sign an OCI artifact using COSE signature format | ||
|
||
# sign a container image using a remote key | ||
notation sign <registry>/<repository>:<tag> | ||
```shell | ||
# Prerequisites: | ||
# A default signing key is configured using CLI "notation key" | ||
|
||
# Use option "--signature-format" to set the signature format to COSE. | ||
$ notation sign --signature-format cose <registry>/<repository>@<digest> | ||
``` | ||
|
||
### Sign an OCI artifact using the default signing key | ||
### Sign an OCI artifact stored in a registry using the default signing key | ||
|
||
```shell | ||
# Prerequisites: | ||
# A default signing key is configured using CLI "notation key" | ||
|
||
# Use a digest that uniquely and immutably identifies an OCI artifact. | ||
notation sign <registry>/<repository>@<digest> | ||
$ notation sign <registry>/<repository>@<digest> | ||
yizha1 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
``` | ||
|
||
### Sign a container image and specify the signature expiry duration, for example 1 day | ||
### Sign an OCI artifact stored in a registry and specify the signature expiry duration, for example 24 hours | ||
|
||
```shell | ||
notation sign --expiry 1d <registry>/<repository>:<tag> | ||
notation sign --expiry 24h <registry>/<repository>@<digest> | ||
priteshbandi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
``` | ||
|
||
### Sign a container image using a specified signing key | ||
### Sign an OCI artifact stored in a registry using a specified signing key | ||
|
||
```shell | ||
# List signing keys to get the key name | ||
notation key list | ||
$ notation key list | ||
yizha1 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
# Sign a container image using the specified key name | ||
notation sign --key <key_name> <registry>/<repository>:<tag> | ||
$ notation sign --key <key_name> <registry>/<repository>@<digest> | ||
``` | ||
|
||
### Sign an OCI artifact identified by a tag | ||
yizha1 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
```shell | ||
# Prerequisites: | ||
# A default signing key is configured using CLI "notation key" | ||
|
||
# Use a tag to identify a container image | ||
$ notation sign <registry>/<repository>:<tag> | ||
``` | ||
|
||
An example for a successful signing: | ||
|
||
```shell | ||
$ notation sign localhost:5000/net-monitor:v1 | ||
Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag(`:latest`) because tags are mutable and a tag reference can point to a different artifact than the one signed. | ||
yizha1 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Resolving artifact tag 'v1' to digest 'sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9' before signing. | ||
yizha1 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 | ||
``` |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It seems not consistent with
notation verify
that the sentence has a dot at the end or not.