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.

Fixes: opencontainers#549

Signed-off-by: Markus Rudy <[email protected]>

spec.md

@@ -180,6 +180,7 @@ The `Docker-Content-Digest` header, if present on the response, returns the cano
 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.
+If the `<reference>` part of a manifest request is a digest, clients SHOULD additionally verify that the response body matches this digest.
 
 If the manifest is not found in the repository, the response code MUST be `404 Not Found`.
 
@@ -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.
 
 If the blob is not found in the repository, the response code MUST be `404 Not Found`.