From e839150a54a90cd2c6cfa4733ac3429b82ee7237 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Mon, 3 Feb 2025 12:27:34 -0800 Subject: [PATCH] spec: Clarify Referrers Tag Schema vs. alternative algorithms From the referenced OCI spec: digest ::= algorithm ":" encoded algorithm ::= algorithm-component (algorithm-separator algorithm-component)* algorithm-component ::= [a-z0-9]+ algorithm-separator ::= [+._-] encoded ::= [a-zA-Z0-9=_-]+ But from the distribution-spec: Throughout this document, `` as a tag MUST be at most 128 characters in length and MUST match the following regular expression: `[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}` Happily, the fist character of algorithm must match algorithm-component, and its [a-z0-9] a subset of the tag regexp's opening [a-zA-Z0-9_]. And the colon separating algorithm from encoded was already addressed in the outgoing text. But the digest definition also allows + in the algorithm-separator and = in the encoded portion, which the tag regexp does not allow, so with the incoming wording I'm requiring that to be replaced by a - as well, so clients make consistent choices when deciding how to handle that character while forming distribution-spec referrer tags. We need some overall truncation to keep the tag under 128 characters, again so clients make consistent choices when trying to compress from the strings the digest specification allows to the strings tags allow. There is no requirement in the distribution spec as far as I can tell that registries support tags up to 128 characters, but given that the spec explicitly requires clients to not exceed that length, it seems likely that registries will allow tags of that length, and not require further truncation. I'm requiring clients to truncate the algothim to 32 characters and the encoded section to 64 characters, because that's one possible reading of the outgoing "limit of 64 characters" parenthetical, at least one client had implemented it that way [1], and Brandon explicitly requested the 32-and-64 approach [2]. And clients are obviously free to create whatever tags they like that the registry will accept. The MUST I'm adding does not forbid that. It only clarifies the single distribution-spec Referrers Tag associated with a given digest, because if there could be multiple Referrers Tag for each digest, all distribution-spec referrer-retrieving clients would have to iterate over that whole set of possibilities, in case some distribution-spec referrer-pushing client happened to use one of that digest's other Referrers Tag formats. [1]: https://github.com/regclient/regclient/blob/dbb1434fd4b8b650983e8c51933789712e05eeaa/types/referrer/referrer.go#L157 [2]: https://github.com/opencontainers/distribution-spec/pull/563#pullrequestreview-2599659231 Signed-off-by: W. Trevor King --- spec.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 26e64b96..8d57a188 100644 --- a/spec.md +++ b/spec.md @@ -721,14 +721,17 @@ A client querying the [referrers API](#listing-referrers) and receiving a `404 N ##### Referrers Tag Schema -```text -- -``` +The Referrers Tag associated with a [Content Digest](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md#digests) [apdx-3](#appendix) MUST match the Truncated Algorithm, a `-` character, and the Truncated Encoded section, with any characters not allowed by [`` tags](#pulling-manifests) replaced with `-`. +The Truncated Algorithm associated with a Content Digest MUST match the digest's `algorithm` section truncated to 32 characters. +The Truncated Encoded section associated with a Content Digest MUST match the digest's `encoded` section truncated to 64 characters. -- ``: the digest algorithm (e.g. `sha256` or `sha512`) -- ``: the digest from the `subject` field (limit of 64 characters) +For example, the following list maps `subject` field digests to Referrers Tags: -For example, a manifest with the `subject` field digest set to `sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa` in the `registry.example.org/project` repository would have a descriptor in the referrers list at `registry.example.org/project:sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`. +| Digest | Truncated Algorithm | Truncated Encoded | Referrers Tag | +| ------ | ------------------- | ----------------- | ------------- | +| sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha256 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | +| sha512:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha512 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha512-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | +| test+algorithm+using+algorithm+separators+and+lots+of+characters+to+excercise+overall+truncation:alsoSome=InTheEncodedSectionToShowHyphenReplacementAndLotsAndLotsOfCharactersToExcerciseEncodedTruncation | test+algorithm+using+algorithm+s | alsoSome=InTheEncodedSectionToShowHyphenReplacementAndLotsAndLot | test-algorithm-using-algorithm-s-alsoSome-InTheEncodedSectionToShowHyphenReplacementAndLotsAndLot | This tag should return an image index matching the expected response of the [referrers API](#listing-referrers). Maintaining the content of this tag is the responsibility of clients pushing and deleting image manifests that contain a `subject` field.