Skip to content

Commit 578ecad

Browse files
SteveLaskerSteveLasker
committed
Renamed as options to keep as reference. Updated digest references
Signed-off-by: Steve Lasker <stevenlasker@hotmail.com>
1 parent 6298cd2 commit 578ecad

1 file changed

Lines changed: 42 additions & 35 deletions

File tree

docs/distribution/README.md renamed to docs/distribution/persistance-discovery-options.md

Lines changed: 42 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
# OCI Distribution - Notary v2 Signature Support
1+
# OCI Distribution - Notary v2 Signature Persistance & Discovery Options
22

3-
To support [Notary v2 goals][notaryv2-goals], upload, Persistence and discovery of signatures must be supported.
3+
> This document explores the various options that were considered for the prototype. The current implementation is documented under the [README.md](./README.md) document.
4+
5+
To support [Notary v2 goals][notaryv2-goals], upload, persistence and discovery of signatures must be supported.
46

57
To minimize the complexity of registry operators and projects to adopt Notary v2, a balance between leveraging what already exists and new patterns to support secure discovery are explored.
68

@@ -171,6 +173,8 @@ Example **manifests** for a container image (`net-monitor:v1`) and two signature
171173

172174
### Signature Persistence - Option 2: oci-index
173175

176+
> **Note:** this is our working prototype/preferred method: See OCI image-spec issue: [Add Index Support for Artifact Type #806](https://github.com/opencontainers/image-spec/issues/806)
177+
174178
This option is similar to using oci-manifest. However, instead of parsing the signature object to determine the linkage between an artifact and signature, the `index.manifests` collection is utilized.
175179

176180
<img src="../../media/signature-as-index.png" width=650>
@@ -318,9 +322,7 @@ Example **manifests** for a container image (`net-monitor:v1`) and two signature
318322

319323
* OCI index does not yet support the [OCI config descriptor][oci-descriptor]. This would require a schema change to oci-index, with a version bump.
320324
* This has been a [desired item for OCI Artifacts][oci-artifacts-index] to support other artifact types which would base on Index.
321-
* An additional role check is performed, based on the artifact type. Also noted as a pro as registry operators may want to utilize this for other artifact types, making it a consistent model.
322-
323-
> **Note:** this is our working/preferred method: See OCI image-spec issue: [Add Index Support for Artifact Type #806](https://github.com/opencontainers/image-spec/issues/806)
325+
* Registries that wish to implement role based authorization would implement and additional role check, based on the artifact type. Also noted as a pro as registry operators may want to utilize this for other artifact types, making it a consistent model. This likely minimizes this as a con-but noted for completeness.
324326

325327
### Signature Persistence - Option 2a: oci-index signing a multi-arch manifest
326328

@@ -661,36 +663,38 @@ Content-Type: application/json
661663

662664
### Signature Discovery - Option 2: Generic Reference Listing API
663665

664-
A slight alternative to the signatures API is to provide a generic reference listing API, where a paged collection of references are returned.
666+
A slight alternative to the signatures API is to provide a generic reference listing API, where a paged collection of references are returned. The intent is to provide a broader usage API, beyond the signature type. For example, returning any multi-arch index references.
665667

666-
In the below example, the `net-monitor:v1` tag has a digest of: `sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042`
668+
<img src="../../media/signature-as-index-signing-multi-arch-index.png" width=950>
669+
670+
Using the diagram above, the `net-monitor:v1` manifest tag (4) has a digest of: `sha256:11wma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a11wm`. When requesting the referenced objects, we see 2 signature objects being returned (wabbit-networks (6) & acme-rockets(7)), and an OCI multi-arch index (1).
667671

668672
```HTTP
669-
GET /v2/<name>/manifests/sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042/references/
673+
GET /v2/<name>/manifests/sha256:11wma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a11wm/references/
670674
```
671675

672-
The response will be in the following format:
676+
The response could be in the following format. Note the additional `config-mediaType` to identify the specific artifact type in the results.
673677

674678
```HTTP
675679
200 OK
676680
Content-Type: application/json
677681
{
678-
"digest": "sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042",
682+
"digest": "sha256:11wma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a11wm",
679683
"references": [
680684
{
681-
"digest": "sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042",
685+
"digest": "sha256:222mbbf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cb222m",
682686
"mediaType": "application/vnd.oci.image.index.v1+json",
683687
"size": "1024",
684688
"config-mediaType": "application/vnd.cncf.notary.config.v2+jwt"
685689
},
686690
{
687-
"digest": "sha256:007170c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75a153b",
691+
"digest": "sha256:333mc0c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75c333m",
688692
"mediaType": "application/vnd.oci.image.index.v1+json",
689693
"size": "1025",
690694
"config-mediaType": "application/vnd.cncf.notary.config.v2+jwt"
691695
},
692696
{
693-
"digest": "sha256:007170c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75a153b",
697+
"digest": "sha256:111ia2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a111i",
694698
"mediaType": "application/vnd.oci.image.index.v1+json",
695699
"size": "1025",
696700
"config-mediaType": "application/vnd.oci.image.index.v1+json"
@@ -717,7 +721,7 @@ Get a list of paginated signatures from the registry. The response will include
717721
Paginated tag results can be retrieved by adding an `n` parameter to the request URL, declaring that the response SHOULD be limited to `n` results. Starting a paginated flow MAY begin as follows:
718722

719723
```HTTP
720-
GET /v2/<name>/manifests/sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042/references/list?n=<integer>
724+
GET /v2/<name>/manifests/sha256:11wma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a11wm/references/list?n=<integer>
721725
```
722726

723727
The above specifies that a tags response SHOULD be returned, from the start of the result set, ordered lexically, limiting the number of results to `n`. The response to such a request would look as follows:
@@ -727,23 +731,23 @@ The above specifies that a tags response SHOULD be returned, from the start of t
727731
Content-Type: application/json
728732
Link: <<url>?n=<n from the request>&last=<last tag value from previous response>>; rel="next"
729733
{
730-
"digest": "sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042",
734+
"digest": "sha256:11wma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a11wm",
731735
"@nextLink": "{opaqueUrl}",
732736
"references": [
733737
{
734-
"digest": "sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042",
738+
"digest": "sha256:222mbbf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cb222m",
735739
"mediaType": "application/vnd.oci.image.index.v1+json",
736740
"size": "1024",
737741
"config-mediaType": "application/vnd.cncf.notary.config.v2+jwt"
738742
},
739743
{
740-
"digest": "sha256:007170c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75a153b",
744+
"digest": "sha256:333mc0c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75c333m",
741745
"mediaType": "application/vnd.oci.image.index.v1+json",
742746
"size": "1025",
743747
"config-mediaType": "application/vnd.cncf.notary.config.v2+jwt"
744748
},
745749
{
746-
"digest": "sha256:007170c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75a153b",
750+
"digest": "sha256:111ia2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a111i",
747751
"mediaType": "application/vnd.oci.image.index.v1+json",
748752
"size": "1025",
749753
"config-mediaType": "application/vnd.oci.image.index.v1+json"
@@ -786,30 +790,30 @@ To support pagination (returning list results in pages) in a List method, the AP
786790
To retrieve the next page of results, client **shall** pass the value of response's `next_page_token` in the subsequent `List` method call (in the request message's `page_token` field):
787791

788792
```HTTP
789-
GET /v2/<name>/manifests/sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042/references/list?page_token=1&page_size=10&next_page_token=<token>
793+
GET /v2/<name>/manifests/sha256:11wma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a11wm/references/list?page_token=1&page_size=10&next_page_token=<token>
790794
```
791795

792796
The above specifies that a tags response SHOULD be returned, from the start of the result set, ordered lexically, limiting the number of results to `n`. The response to such a request would look as follows:
793797

794798
```json
795799
{
796-
"digest": "sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042",
800+
"digest": "sha256:11wma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a11wm",
797801
"@next_page_token": "{opaqueUrl}",
798802
"references": [
799803
{
800-
"digest": "sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042",
804+
"digest": "sha256:222mbbf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cb222m",
801805
"mediaType": "application/vnd.oci.image.index.v1+json",
802806
"size": "1024",
803807
"config-mediaType": "application/vnd.cncf.notary.config.v2+jwt"
804808
},
805809
{
806-
"digest": "sha256:007170c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75a153b",
810+
"digest": "sha256:333mc0c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75c333m",
807811
"mediaType": "application/vnd.oci.image.index.v1+json",
808812
"size": "1025",
809813
"config-mediaType": "application/vnd.cncf.notary.config.v2+jwt"
810814
},
811815
{
812-
"digest": "sha256:007170c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75a153b",
816+
"digest": "sha256:111ia2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a111i",
813817
"mediaType": "application/vnd.oci.image.index.v1+json",
814818
"size": "1025",
815819
"config-mediaType": "application/vnd.oci.image.index.v1+json"
@@ -838,15 +842,18 @@ These assume:
838842

839843
### Artifacts submitted to a registry
840844

841-
The following are artifacts that represent a container image, or signature artifact. Depending on the example above, the signatures are represented as an oci manifest or oci index.
842-
|Artifact |`config.mediaType` | Digest |
843-
|--------------------------------------|-------------------------------------------|-------------------------------------------------------------------------|
844-
|`net-monitor:v1` image **manifest** |`application/vnd.oci.image.config.v1+json` |`sha256:111ma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a111m`|
845-
|`net-monitor:v1` multi-arch **index** |`application/vnd.oci.image.config.v1+json` |`sha256:111ia2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a111i`|
846-
|wabbit-networks signature **manifest**|`application/vnd.cncf.notary.config.v2+jwt`|`sha256:222mbbf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cb222m`|
847-
|wabbit-networks signature **index** |`application/vnd.cncf.notary.config.v2+jwt`|`sha256:222ibbf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cb222i`|
848-
|acme-rockets signature **manifest** |`application/vnd.cncf.notary.config.v2+jwt`|`sha256:333mc0c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75c333m`|
849-
|acme-rockets signature **index** |`application/vnd.cncf.notary.config.v2+jwt`|`sha256:333ic0c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75c333i`|
845+
The following are artifacts that represent container images and signature artifacts. Depending on the example above, the signatures are represented as an oci manifest or oci index. Some tags are re-used to represent platform neutral examples. For instance, `net-monitor:v1` is represented as both a default linux image manifest, and a multi-arch index. In some examples, the platform is removed from the tag for brevity and focus on the topic at hand. _It is not suggested `:v1` tags can point to multiple things at the same time._
846+
847+
|Artifact |`config.mediaType` | Digest |
848+
|------------------------------------------|-------------------------------------------|-------------------------------------------------------------------------|
849+
|`net-monitor:v1` image **manifest** |`application/vnd.oci.image.config.v1+json` |`sha256:111ma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a111m`|
850+
|`net-monitor:v1-linux` image **manifest** |`application/vnd.oci.image.config.v1+json` |`sha256:11lma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a11lm`|
851+
|`net-monitor:v1-win` image **manifest** |`application/vnd.oci.image.config.v1+json` |`sha256:11wma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a11wm`|
852+
|`net-monitor:v1` multi-arch **index** |`application/vnd.oci.image.config.v1+json` |`sha256:111ia2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a111i`|
853+
|wabbit-networks signature **manifest** |`application/vnd.cncf.notary.config.v2+jwt`|`sha256:222mbbf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cb222m`|
854+
|wabbit-networks signature **index** |`application/vnd.cncf.notary.config.v2+jwt`|`sha256:222ibbf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cb222i`|
855+
|acme-rockets signature **manifest** |`application/vnd.cncf.notary.config.v2+jwt`|`sha256:333mc0c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75c333m`|
856+
|acme-rockets signature **index** |`application/vnd.cncf.notary.config.v2+jwt`|`sha256:333ic0c33ebc4a74a0a554c86ac2b28ddf3454a5ad9cf90ea8cea9f9e75c333i`|
850857

851858
### Config Objects - referenced by manifests
852859

@@ -858,15 +865,15 @@ The following are descriptors, representing config objects within a manifest and
858865
|wabbit-networks signature |`sha256:222cb130c152895905abe66279dd9feaa68091ba55619f5b900f2ebed38b222c`|
859866
|acme-rockets signature |`sha256:333cc44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b785c333c`|
860867

861-
### Example manifest for the **container image**: `registry.acme-rockets.com/net-monitor:v1`
868+
### Example manifest for the platform agnostic **container image**: `registry.acme-rockets.com/net-monitor:v1`
862869

863870
```json
864871
{
865872
"schemaVersion": 2,
866873
"mediaType": "application/vnd.oci.image.manifest.v2+json",
867874
"config": {
868875
"mediaType": "application/vnd.oci.image.config.v1+json",
869-
"digest": "sha256:1101a3788f3464fd9a06386c4d7a8e3018b525278ac4b9da872943d4cfe97fe8",
876+
"digest": "sha256:111ma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a111m",
870877
"size": 1906
871878
},
872879
"layers": [
@@ -891,7 +898,7 @@ See [nv2 signature spec][nv2-signature-spec] for more details.
891898
```json
892899
{
893900
"signed": {
894-
"digest": "sha256:2235d2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49cc77c",
901+
"digest": "sha256:111ma2d22ae5ef400769fa51c84717264cd1520ac8d93dc071374c1be49a111m",
895902
"size": 528,
896903
"references": [
897904
"registry.acme-rockets.com/net-monitor:v1"

0 commit comments

Comments
 (0)