Explicitly recommend content digest information #556
Conversation
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. Fixes: opencontainers#549 Signed-off-by: Markus Rudy <[email protected]>
burgerdev
requested review from
dmcgowan,
jzelinskie,
jonjohnsonjr,
jdolitsky,
mikebrow,
stevvooe and
sudo-bmitch
as code owners
| @@ -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. | |||
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
What I meant to say with this sentence is that
- clients should always verify the requested digest
- if a response header digest is present, clients should verify that, too
- implicitly, a blob should not be stored at all if it fails any of the above
Do you think I should make (3) explicit?
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
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 [...]
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Ok, let's keep it as is, then.
There was a problem hiding this comment.
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.
| 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. |
| @@ -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. | |||
There was a problem hiding this comment.
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.
| 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. |
Co-authored-by: Brandon Mitchell <[email protected]> Signed-off-by: Markus Rudy <[email protected]>
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.
Fixes: #549
cc @sudo-bmitch