doc: update spec for feature sign/verify local images

[yizha1]

Update specs for feature sign/verify local images

Signed-off-by: Yi Zha yizha1@microsoft.com

[codecov-commenter]

Codecov Report

Merging #601 (a310de7) into main (124c6c8) will decrease coverage by 0.73%.
The diff coverage is n/a.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

@@            Coverage Diff             @@
##             main     #601      +/-   ##
==========================================
- Coverage   34.36%   33.63%   -0.73%     
==========================================
  Files          32       32              
  Lines        1848     1888      +40     
==========================================
  Hits          635      635              
- Misses       1192     1232      +40     
  Partials       21       21              

see 4 files with indirect coverage changes

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

[byronchien]

should notation inspect also support local signatures/images?

[sajayantony]

1. Can we considering inferring that its a file path? @priteshbandi also brought this up.
2. Secondly if the flag is needed can we call it something like --file or --path etc. --local is quite subjective.

[kody-kimberl]

For the option, what if we considered something more flexible than just a boolean. If we use something like --type (maybe this isn't the best name, but I think the concept is interesting) we could specify through the option that it is a directory. That would allow us to easily incorporate new modes for tarballs, SBOMs, or other files that could be added in the future.

---

Example:

notation sign $IMAGE
notation sign --type dir /path/to/registry.acme-rockets.io/net-monitor:v2
notation sign --type tar hello-world.tar
...

[yizha1]

@shizhMSFT @patrickzheng200 @qweeah @priteshbandi @vaninrao10 @FeynmanZhou @toddysm @sajayantony please take a look at Kody's comment above. Now we have these options:

1. --local-content
2. --local-artifact
3. --path <file path | dir path>
4. --file
5. --use-oci-layout
6. --oci-dir
7. --offline
8. file://./
9. --dirpath
10. --target-path
11. --type <dir|tar|other types>

[patrickzheng200]

In fact, if @yizha1 could remember, the very first version of my design was pretty similar to Kody's suggestion, i.e. specifying type of the user input. So personally speaking, I think it's a good idea as long as there's no usability concern (users need to know what options are available in Notation, and what type their input belong to).

[yizha1]

I vote for option 3: --path <file path | dir path>

[FeynmanZhou]

Agree with adding --target type=... flag in v1.0.0. There is only one target type oci-layout in RC.4, it's reasonable to use --oci-layout as a shorthand for --target type=oci-layout.

[toddysm]

I am not sure having shorthand is a good idea. Having too many switches pollutes the CLI and makes its use hard to use.

[yizha1]

@toddysm We will consider adding --target type= if the time allows for 1.0. For RC.4 it is a good start, since we only have one type now, compared to --target type=oci-layout, --oci-layout is short and convenient. Shorthand could be a good practice for some scenarios, if we have multiple choice, and we know what option 80% users will choose, then shorthand will be convenient for them, since it is short. In the meantime, we could also support 20% scenarios with the full flag. In our cases, OCI image layout could be the most choice, since it is the only standard now OCI images and other OCI artifacts can be stored in a directory structure under filesystem (could be completely offline), and easy to copy to remote registry.

[toddysm]

My problem is that the main scenario is not that one. People do not want to create the layout before signing. A good user experience will be to reference the docker image and do all the work behind the scenes. Also, another local signing scenario is just signing a blob, like file for example, which doesn't require OCI layout at all. The current experience to ask the user to expand the image in OCI layout is suboptimal. If this is the only option then yes - this will be > 80% of the cases but it is a very little percentage of what people really want to do.

[yizha1]

As discussed, --oci-layout and --scope will be experimental feature which requires system variable NOTATION_EXPERIMENTAL to be set.

[yizha1]

should notation inspect also support local signatures/images?

notation inspect will come in later release. The plan is to implement sign/verify local images in a phased approach. There are other scenarios and commands not covered yet.

[shizhMSFT]

--path and other generic terms are ambiguous if we want to sign a single file in the future. For instance, --path a.tar can mean that we are processing the a.tar as it is or the content in the a.tar.

In fact, I think --type <type> makes more sense. cobra also allows use to type --type=<type> For examples,

• --type=oci or --type=dir for OCI-Layout in a folder
• --type=oci or --type=tar for OCI-layout in a tarball
• --type=file is reserved for future file signing
• --type=desc is reserved for future descriptor signing

However, --type=<type> is still not straightforward.

As a reference, oras introduces the following flag:

--target type=<type>[[,<key>=<value>][...]]

For better UX, the boolean flag --oci-layout is introduced as an alias of --target type=oci-layout.

Similarly, we could also follow the practice of oras.

notation sign registry.acme-rockets.io/net-monitor:v2                     # remote registry
notation sign --oci-layout registry.acme-rockets.io/net-monitor:v2        # oci-layout folder
notation sign --oci-layout net-monitor.tar:v2 --output net-monitor_v2.sig # oci-layout tarball
notation sign --descriptor desc.json --output desc.sig                    # descriptor
notation sign --file file.bin --output file.sig                           # standalone file

notation list registry.acme-rockets.io/net-monitor:v2              # remote registry
notation list --oci-layout registry.acme-rockets.io/net-monitor:v2 # oci-layout folder
notation list --oci-layout net-monitor.tar:v2                      # oci-layout tarball

notation verify registry.acme-rockets.io/net-monitor:v2                                                           # remote registry
notation verify --scope registry.acme-rockets.io/net-monitor --oci-layout registry.acme-rockets.io/net-monitor:v2 # oci-layout folder
notation verify --scope registry.acme-rockets.io/net-monitor --oci-layout net-monitor.tar:v2                      # oci-layout tarball
notation verify --scope registry.acme-rockets.io/net-monitor --descriptor desc.json --signature desc.sig          # descriptor
notation verify --scope registry.acme-rockets.io/net-monitor --file file.bin --signature file.sig                 # standalone file

[patrickzheng200]

LGTM

[patrickzheng200]

LGTM

[priteshbandi]

LGTM

[patrickzheng200]

LGTM