From 24084d4f7297d2c7cdc8c6c9cf78dbdf69f7a055 Mon Sep 17 00:00:00 2001 From: Markus Rudy Date: Wed, 16 Oct 2024 09:12:27 +0200 Subject: [PATCH] Explicitly recommend content digest information The spec mandated only the verification of digests in the response headers, not the requested digests. That allowed conformant clients not to validate content at all, leaving the users of these clients exposed to accidental or malicious bad content. This commit adds a "SHOULD verify" clause to the blob and manifest pull sections. It's not a MUST to keep it somewhat backwards compatible with requirements of 1.1 and prior, but it's not a MAY to convey that "the full implications should be understood and the case carefully weighed" (description in RFC 2119) for a client not to verify digests. This commit also aligns the recommendations for server-returned digests between manifest and blob - now both can be ignored, but must be verified if used. Fixes: #549 Co-authored-by: Brandon Mitchell Signed-off-by: Markus Rudy --- spec.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index d5d769c2..26e64b96 100644 --- a/spec.md +++ b/spec.md @@ -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) [apdx-3](#appendix) 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 `` 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`. @@ -193,6 +194,8 @@ 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. +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`.