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

Jump to bottom

Explicitly recommend content digest information #556

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+3 −1
Open

Explicitly recommend content digest information #556

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cb10c2a
Explicitly recommend content digest information
burgerdev Oct 16, 2024
4ef3a4f
Explicitly refer to manifests as verification objects
burgerdev Oct 29, 2024
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
4 changes: 3 additions & 1 deletion spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,8 @@ A successful response SHOULD contain the digest of the uploaded blob in the head
The `Docker-Content-Digest` header, if present on the response, returns the canonical digest of the uploaded blob which MAY differ from the provided digest.
If the digest does differ, it MAY be the case that the hashing algorithms used do not match.
See [Content Digests](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md#digests) <sup>[apdx-3](#appendix)</sup> for information on how to detect the hashing algorithm in use.
Most clients MAY ignore the value, but if it is used, the client MUST verify the value against the uploaded blob data.
Most clients MAY ignore the value, but if it is used, the client MUST verify the value matches the returned manifest.
If the `<reference>` part of a manifest request is a digest, clients SHOULD verify the returned manifest matches this digest.

If the manifest is not found in the repository, the response code MUST be `404 Not Found`.

Expand All @@ -193,6 +194,7 @@ To pull a blob, perform a `GET` request to a URL in the following form:
A GET request to an existing blob URL MUST provide the expected blob, with a response code that MUST be `200 OK`.
A successful response SHOULD contain the digest of the uploaded blob in the header `Docker-Content-Digest`.
If present, the value of this header MUST be a digest matching that of the response body.
Clients SHOULD verify that the response body matches the requested digest and the response header digest.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The registry could return a header digest with another algorithm, in that case the client should not trust the digest if it does not match but would need to verify the manifest against the client's digest reference and registries digest (if the client intends to store the content by the registry provided digest).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I meant to say with this sentence is that

  1. clients should always verify the requested digest
  2. if a response header digest is present, clients should verify that, too
  3. implicitly, a blob should not be stored at all if it fails any of the above

Do you think I should make (3) explicit?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From our discussions in yesterday's meeting, we didn't feel it necessary for clients to verify a potentially different digest algorithm, particularly if the server supports different algorithms than that client supports, and the client didn't request them.

Suggested change
Clients SHOULD verify that the response body matches the requested digest and the response header digest.
Clients SHOULD verify that the response body matches the requested digest.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that clients should not need to verify the digest header if they're not using it, but should we ask them to do it when they use it, similar to the requirements for the manifest?

Most clients MAY ignore the value, but if it is used, the client MUST verify the value [...]

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see the value-add in verifying the server provided header. This digest is always known by the client, and needs to match the descriptor value in a manifest. If the server gives a different algorithm, there's no workflow where the pulling client should use that digest even if it verified it.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, let's keep it as is, then.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd still like to change it. But we can add a line similar to 182 to cover any clients that later find a use case for the data.

Suggested change
Clients SHOULD verify that the response body matches the requested digest and the response header digest.
Most clients MAY ignore the value, but if it is used, the client MUST verify the value matches the returned response body.
Clients SHOULD verify that the response body matches the requested digest.


If the blob is not found in the repository, the response code MUST be `404 Not Found`.

Expand Down