Digest Fields

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 31 March 2022.¶

Copyright Notice

Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶

Table of Contents

1. Introduction

HTTP does not define a means to protect the integrity of representations. When HTTP messages are transferred between endpoints, the protocol might choose to make use of features of the lower layer in order to provide some integrity protection; for instance, TCP checksums or TLS records [RFC2818].¶

This document defines two digest integrity mechanisms for HTTP. First, representation data integrity, which acts on representation data (Section 3.2 of [SEMANTICS]). Second, content digest integrity, which acts on conveyed content (Section 6.4 of [SEMANTICS]). Both mechanisms operate independent of transport integrity, offering the potential to detect programming errors and corruption of data in flight or at rest. They can be used across multiple hops in order to provide end-to-end integrity guarantees, which can aid fault diagnosis when resources are transferred across hops and system boundaries. Finally, they can be used to validate integrity when reconstructing a resource fetched using different HTTP connections.¶

This document obsoletes [RFC3230].¶

2. Representation Digest

The representation digest is an integrity mechanism for HTTP resources which uses a checksum that is calculated independently of the content (see Section 6.4 of [SEMANTICS]). It uses the representation data (see Section 8.1 of [SEMANTICS]), that can be fully or partially contained in the content, or not contained at all.¶

This takes into account the effect of the HTTP semantics on the messages; for example, the content can be affected by Range Requests or methods such as HEAD, while the way the content is transferred "on the wire" is dependent on other transformations (e.g. transfer codings for HTTP/1.1 - see Section 6.1 of [HTTP11]). To help illustrate how such things affect Digest, several examples are provided in Appendix A.¶

A representation digest consists of the value of a checksum computed on the entire selected representation data (see Section 8.1 of [SEMANTICS]) of a resource identified according to Section 6.4.2 of [SEMANTICS] together with an indication of the algorithm used:¶

   representation-data-digest = digest-algorithm "="
                                <encoded digest output>

When a message has no representation data it is still possible to assert that no representation data was sent computing the representation digest on an empty string (see Section 8.3).¶

The checksum is computed using one of the digest-algorithms listed in the HTTP Digest Algorithm Values Registry (see Section 6) and then encoded in the associated format.¶

3. The Digest Field

The Digest field contains a comma-separated list of one or more representation digest values as defined in Section 2. It can be used in both requests and responses.¶

   Digest = 1#representation-data-digest

For example:¶

Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm
                   AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==

A Digest field MAY contain multiple representation-data-digest values. For example, a server may provide representation-data-digest values using different algorithms, allowing it to support a population of clients with different evolving capabilities; this is particularly useful in support of transitioning away from weaker algorithms should the need arise (see Section 8.6).¶

Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=,
        id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

A recipient MAY ignore any or all of the representation-data-digests in a Digest field. This allows the recipient to choose which digest-algorithm(s) to use for validation instead of verifying every received representation-data-digest.¶

A sender MAY send a representation-data-digest using a digest-algorithm without knowing whether the recipient supports the digest-algorithm, or even knowing that the recipient will ignore it.¶

Digest can be sent in a trailer section. In this case, Digest MAY be merged into the header section; see Section 6.5.1 of [SEMANTICS].¶

When an incremental digest-algorithm is used, the sender and the receiver can dynamically compute the digest value while streaming the content.¶

A non-comprehensive set of examples showing the impacts of representation metadata, payload transformations and HTTP methods on Digest is provided in Appendix B and Appendix C.¶

4. The Content-Digest Field

The Content-Digest field contains a comma-separated list of one or more content digest values. A content digest value is computed by applying a digest-algorithm to the actual message content (see Section 6.4 of [SEMANTICS]). It can be used in both requests and responses.¶

   Content-Digest = 1#content-digest
   content-digest = digest-algorithm "="
                    <encoded digest output>

For example:¶

Content-Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm
                           AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==

A Content-Digest field MAY contain multiple content-digest values, similarly to Digest (see Section 3)¶

Content-Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=,
                id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

A recipient MAY ignore any or all of the content-digests in a Content-Digest field. This allows the recipient to choose which digest-algorithm(s) to use for validation instead of verifying every received content-digest.¶

A sender MAY send a content-digest using a digest-algorithm without knowing whether the recipient supports the digest-algorithm, or even knowing that the recipient will ignore it.¶

Content-Digest can be sent in a trailer section. In this case, Content-Digest MAY be merged into the header section; see Section 6.5.1 of [SEMANTICS].¶

When an incremental digest-algorithm is used, the sender and the receiver can dynamically compute the digest value while streaming the content.¶

5. Want-Digest and Want-Content-Digest Fields

Senders can indicate their integrity checksum preferences using the Want-Digest or Want-Content-Digest fields. These can be used in both requests and responses.¶

Want-Digest indicates the sender's desire to receive a representation digest on messages associated with the request URI and representation metadata, using the Digest field.¶

Want-Content-Digest indicates the sender's desire to receive a content digest on messages associated with the request URI and representation metadata, using the Content-Digest field.¶

   Want-Digest = 1#want-digest-value
   Want-Content-Digest = 1#want-digest-value
   want-digest-value = digest-algorithm [ ";" "q" "=" qvalue]

qvalue indicates the sender's digest-algorithm preferences. Section 12.4.2 of [SEMANTICS]) describes qvalue usage and semantics.¶

Senders can provide multiple digest-algorithm items with the same qvalue.¶

Examples:¶

Want-Digest: sha-256
Want-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0
Want-Content-Digest: sha-256
Want-Content-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0

6. Digest Algorithm Values

Digest-algorithm values are used to indicate a specific digest computation.¶

   digest-algorithm = token

All digest-algorithm token values are case-insensitive but lower case is preferred; digest-algorithm token values MUST be compared in a case-insensitive fashion.¶

Every digest-algorithm defines its computation procedure and encoding output. Unless specified otherwise, comparison of encoded output is case-sensitive.¶

The "HTTP Digest Algorithm Values Registry", maintained by IANA at https://www.iana.org/assignments/http-dig-alg/ registers digest-algorithm values. Registrations MUST include the following fields:¶

• Digest algorithm: the token value. The registry can be used to reserve token values¶

• Status: the status of the algorithm. Use "standard" for standardized algorithms without known problems; "experimental" or some other appropriate value¶

  • e.g. according to the type and status of the primary document in which the algorithm is defined; "deprecated" when the algorithm is insecure or otherwise undesirable; "reserved" when Digest algorithm references a reserved token value¶
• Description: the description of the digest-algorithm and its encoding¶
• Reference: a set of pointers to the primary documents defining the digest-algorithm¶

The associated encoding for new digest-algorithms MUST either be represented as a quoted string or MUST NOT include ";" or "," in the character sets used for the encoding.¶

Deprecated digest algorithms MUST NOT be used.¶

The registry is initialized with the tokens listed below.¶

sha-512

• Digest Algorithm: sha-512¶
• Description: The SHA-512 algorithm [RFC6234]. The output of this algorithm is encoded using the base64 encoding [RFC4648].¶
• Reference: [RFC6234], [RFC4648], this document.¶
• Status: standard¶

sha-256

• Digest Algorithm: sha-256¶
• Description: The SHA-256 algorithm [RFC6234]. The output of this algorithm is encoded using the base64 encoding [RFC4648].¶
• Reference: [RFC6234], [RFC4648], this document.¶
• Status: standard¶

md5

• Digest Algorithm: md5¶
• Description: The MD5 algorithm, as specified in [RFC1321]. The output of this algorithm is encoded using the base64 encoding [RFC4648]. This digest-algorithm is now vulnerable to collision attacks. See [NO-MD5] and [CMU-836068].¶
• Reference: [RFC1321], [RFC4648], this document.¶
• Status: deprecated¶

sha

• Digest Algorithm: sha¶
• Description: The SHA-1 algorithm [RFC3174]. The output of this algorithm is encoded using the base64 encoding [RFC4648]. This digest-algorithm is now vulnerable to collision attacks. See [NO-SHA1] and [IACR-2020-014].¶
• Reference: [RFC3174], [RFC6234], [RFC4648], this document.¶
• Status: deprecated¶

unixsum

• Digest Algorithm: unixsum¶
• Description: The algorithm computed by the UNIX "sum" command, as defined by the Single UNIX Specification, Version 2 [UNIX]. The output of this algorithm is an ASCII decimal-digit string representing the 16-bit checksum, which is the first word of the output of the UNIX "sum" command.¶
• Reference: [UNIX], this document.¶
• Status: deprecated¶

unixcksum

• Digest Algorithm: unixcksum¶
• Description: The algorithm computed by the UNIX "cksum" command, as defined by the Single UNIX Specification, Version 2 [UNIX]. The output of this algorithm is an ASCII digit string representing the 32-bit CRC, which is the first word of the output of the UNIX "cksum" command.¶
• Reference: [UNIX], this document.¶
• Status: deprecated¶

adler32

• Digest Algorithm: adler32¶
• Description: The ADLER32 algorithm is a checksum specified in [RFC1950] "ZLIB Compressed Data Format". The 32-bit output is encoded in hexadecimal (using between 1 and 8 ASCII characters from 0-9, A-F, and a-f; leading 0's are allowed). For example, adler32=03da0195 and adler32=3DA0195 are both valid checksums for the 4-byte message "Wiki". This algorithm is obsoleted and SHOULD NOT be used.¶
• Reference: [RFC1950], this document.¶
• Status: deprecated¶

crc32c

• Digest Algorithm: crc32c¶
• Description: The CRC32c algorithm is a 32-bit cyclic redundancy check. It achieves a better hamming distance (for better error-detection performance) than many other 32-bit CRC functions. Other places it is used include iSCSI and SCTP. The 32-bit output is encoded in hexadecimal (using between 1 and 8 ASCII characters from 0-9, A-F, and a-f; leading 0's are allowed). For example, crc32c=0a72a4df and crc32c=A72A4DF are both valid checksums for the 3-byte message "dog".¶
• Reference: [RFC4960] appendix B, this document.¶
• Status: deprecated.¶

To allow sender and recipient to provide a checksum which is independent from Content-Encoding, the following additional digest-algorithms are defined:¶

id-sha-512

• Description: The sha-512 digest of the representation data of the resource when no content coding is applied¶
• Reference: [RFC6234], [RFC4648], this document.¶
• Status: standard¶

id-sha-256

• Description: The sha-256 digest of the representation data of the resource when no content coding is applied¶
• Reference: [RFC6234], [RFC4648], this document.¶
• Status: standard¶

7. Using Digest in State-Changing Requests

When the representation enclosed in a state-changing request does not describe the target resource, the representation digest MUST be computed on the representation-data. This is the only possible choice because representation digest requires complete representation metadata (see Section 2).¶

In responses,¶

• if the representation describes the status of the request, Digest MUST be computed on the enclosed representation (see Appendix B.8 );¶
• if there is a referenced resource Digest MUST be computed on the selected representation of the referenced resource even if that is different from the target resource. That might or might not result in computing Digest on the enclosed representation.¶

The latter case is done according to the HTTP semantics of the given method, for example using the Content-Location header field (see Section 8.7 of [SEMANTICS]). In contrast, the Location header field does not affect Digest because it is not representation metadata.¶

For example, in PATCH requests, the representation digest will be computed on the patch document because the representation metadata refers to the patch document and not to the target resource (see Section 2 of [PATCH]). In responses, instead, the representation digest will be computed on the selected representation of the patched resource.¶

8. Security Considerations

Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=,
        sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

9. IANA Considerations

Appendix A. Resource Representation and Representation-Data

The following examples show how representation metadata, payload transformations and method impacts on the message and content. When the content contains non-printable characters (e.g. when it is compressed) it is shown as a Base64-encoded string.¶

PUT /entries/1234 HTTP/1.1
Host: foo.example
Content-Type: application/json

{"hello": "world"}

PUT /entries/1234 HTTP/1.1
Host: foo.example
Content-Type: application/json
Content-Encoding: gzip

H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA=

Now the same content conveys a malformed JSON object, because the request does not indicate a content coding.¶

PUT /entries/1234 HTTP/1.1
Host: foo.example
Content-Type: application/json

H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA=

A Range-Request alters the content, conveying a partial representation.¶

GET /entries/1234 HTTP/1.1
Host: foo.example
Range: bytes=1-7

HTTP/1.1 206 Partial Content
Content-Encoding: gzip
Content-Type: application/json
Content-Range: bytes 1-7/18

iwgAla3RXA==

The method can also alter the content. For example, the response to a HEAD request does not carry content.¶

HEAD /entries/1234 HTTP/1.1
Host: foo.example
Accept: application/json
Accept-Encoding: gzip

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip

Finally, the semantics of an HTTP response might decouple the effective request URI from the enclosed representation. In the example response below, the Content-Location header field indicates that the enclosed representation refers to the resource available at /authors/123, even though the request is directed to /authors/.¶

POST /authors/ HTTP/1.1
Host: foo.example
Accept: application/json
Content-Type: application/json

{"author": "Camilleri"}

HTTP/1.1 201 Created
Content-Type: application/json
Content-Location: /authors/123
Location: /authors/123

{"id": "123", "author": "Camilleri"}

Appendix B. Examples of Unsolicited Digest

The following examples demonstrate interactions where a server responds with a Digest or Content-Digest fields even though the client did not solicit one using Want-Digest or Want-Content-Digest.¶

Some examples include JSON objects in the content. For presentation purposes, objects that fit completely within the line-length limits are presented on a single line using compact notation with no leading space. Objects that would exceed line-length limits are presented across multiple lines (one line per key-value pair) with 2 spaced of leading indentation.¶

Checksum mechanisms defined in this document are media-type agnostic and do not provide canonicalization algorithms for specific formats. Examples are calculated inclusive of any space. While examples can include both fields, Digest and Content-Digest can be returned independently.¶

GET /items/123 HTTP/1.1
Host: foo.example

HTTP/1.1 200 OK
Content-Type: application/json
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
Content-Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

{"hello": "world"}

HEAD /items/123 HTTP/1.1
Host: foo.example

HTTP/1.1 200 OK
Content-Type: application/json
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
Content-Digest: sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

GET /items/123 HTTP/1.1
Host: foo.example
Range: bytes=1-7

HTTP/1.1 206 Partial Content
Content-Type: application/json
Content-Range: bytes 1-7/18
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
Content-Digest: sha-256=Wqdirjg/u3J688ejbUlApbjECpiUUtIwT8lY/z81Tno=

"hello"

PUT /items/123 HTTP/1.1
Host: foo.example
Content-Type: application/json
Accept-Encoding: br
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

{"hello": "world"}

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /items/123
Content-Encoding: br
Content-Length: 22
Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=

iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw==

PUT /items/123 HTTP/1.1
Host: foo.example
Content-Type: application/json
Content-Length: 18
Accept-Encoding: br
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

{"hello": "world"}

HTTP/1.1 204 No Content
Content-Type: application/json
Content-Encoding: br
Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=

PUT /items/123 HTTP/1.1
Host: foo.example
Content-Type: application/json
Accept-Encoding: br
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

{"hello": "world"}

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: br
Content-Location: /items/123
Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=,
        id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw==

POST /books HTTP/1.1
Host: foo.example
Content-Type: application/json
Accept: application/json
Accept-Encoding: identity
Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=

{"title": "New Title"}

HTTP/1.1 201 Created
Content-Type: application/json
Content-Location: /books/123
Location: /books/123
Digest: id-sha-256=yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE=

{
  "id": "123",
  "title": "New Title"
}

POST /books HTTP/1.1
Host: foo.example
Content-Type: application/json
Accept: application/json
Accept-Encoding: identity
Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=

{"title": "New Title"}

HTTP/1.1 201 Created
Content-Type: application/json
Digest: id-sha-256=2LBp5RKZGpsSNf8BPXlXrX4Td4Tf5R5bZ9z7kdi5VvY=
Location: /books/123

{
  "status": "created",
  "id": "123",
  "ts": 1569327729,
  "instance": "/books/123"
}

PATCH /books/123 HTTP/1.1
Host: foo.example
Content-Type: application/merge-patch+json
Accept: application/json
Accept-Encoding: identity
Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=

{"title": "New Title"}

HTTP/1.1 200 OK
Content-Type: application/json
Digest: id-sha-256=yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE=

{
  "id": "123",
  "title": "New Title"
}

HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Digest: sha-256=KPqhVXAT25LLitV1w0O167unHmVQusu+fpxm65zAsvk=

{
  "title": "Not Found",
  "detail": "Cannot PATCH a non-existent resource",
  "status": 404
}

GET /items/123 HTTP/1.1
Host: foo.example

HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Trailer: Digest

8\r\n
{"hello"\r\n
8
: "world\r\n
2\r\n
"}\r\n
0\r\n
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

Appendix C. Examples of Want-Digest Solicited Digest

The following examples demonstrate interactions where a client solicits a Digest using Want-Digest. The behavior of Content-Digest and Want-Content-Digest is identical.¶

Some examples include JSON objects in the content. For presentation purposes, objects that fit completely within the line-length limits are presented on a single line using compact notation with no leading space. Objects that would exceed line-length limits are presented across multiple lines (one line per key-value pair) with 2 spaced of leading indentation.¶

Checksum mechanisms described in this document are media-type agnostic and do not provide canonicalization algorithms for specific formats. Examples are calculated inclusive of any space.¶

GET /items/123 HTTP/1.1
Host: foo.example
Want-Digest: sha-256;q=0.3, sha;q=1

HTTP/1.1 200 OK
Content-Type: application/json
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

{"hello": "world"}

GET /items/123 HTTP/1.1
Host: foo.example
Want-Digest: sha;q=1

HTTP/1.1 200 OK
Content-Type: application/json
Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm
                   +AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==

{"hello": "world"}

GET /items/123 HTTP/1.1
Host: foo.example
Want-Digest: sha;q=1

HTTP/1.1 400 Bad Request
Want-Digest: sha-256, sha-512

Appendix D. Changes from RFC3230

Acknowledgements

The vast majority of this document is inherited from [RFC3230], so thanks to J. Mogul and A. Van Hoff for their great work. The original idea of refreshing this document arose from an interesting discussion with M. Nottingham, J. Yasskin and M. Thomson when reviewing the MICE content coding.¶

Thanks to Julian Reschke for his valuable contributions to this document, and to the following contributors that have helped improve this specification by reporting bugs, asking smart questions, drafting or reviewing text, and evaluating open issues: Mike Bishop, Brian Campbell, Matthew Kerwin, James Manger, Tommy Pauly, Sean Turner, and Erik Wilde.¶

FAQ

RFC Editor: Please remove this section before publication.¶

1. Why remove all references to content-md5?¶

   Those were unnecessary to understanding and using this specification.¶

2. Why remove references to instance manipulation?¶

   Those were unnecessary for correctly using and applying the specification. An example with Range Request is more than enough. This document uses the term "partial representation" which should group all those cases.¶

3. How to use Digest with PATCH method?¶

   See Section 7.¶

4. Why remove references to delta-encoding?¶

   Unnecessary for a correct implementation of this specification. The revised specification can be nicely adapted to "delta encoding", but all the references here to delta encoding don't add anything to this RFC. Another job would be to refresh delta encoding.¶

5. Why remove references to Digest Authentication?¶

   This specification seems to me completely unrelated to Digest Authentication but for the word "Digest".¶

6. What changes in Want-Digest?¶

   The contentMD5 token defined in Section 5 of [RFC3230] is deprecated by Appendix D.1.¶

   To clarify that Digest and Want-Digest can be used in both requests and responses - [RFC3230] carefully uses sender and receiver in their definition - we added examples on using Want-Digest in responses to advertise the supported digest-algorithms and the inability to accept requests with unsupported digest-algorithms.¶

7. Does this specification change supported algorithms?¶

   Yes. This RFC updates [RFC5843] which is still delegated for all algorithms updates, and adds two more algorithms: "id-sha-256" and "id-sha-512" which allows to send a checksum of a resource representation with no content codings applied. To simplify a future transition to Structured Fields [I-D.ietf-httpbis-header-structure] we suggest to use lowercase for digest-algorithms.¶

8. What about mid-stream trailer fields?¶

   While mid-stream trailer fields are interesting, since this specification is a rewrite of [RFC3230] we do not think we should face that. As a first thought, nothing in this document precludes future work that would find a use for mid-stream trailers, for example an incremental digest-algorithm. A document defining such a digest-algorithm is best positioned to describe how it is used.¶

Code Samples

RFC Editor: Please remove this section before publication.¶

How can I generate and validate the Digest values shown in the examples throughout this document?¶

The following python3 code can be used to generate digests for JSON objects using SHA algorithms for a range of encodings. Note that these are formatted as base64. This function could be adapted to other algorithms and should take into account their specific formatting rules.¶

import base64, json, hashlib, brotli, logging
log = logging.getLogger()

def encode_item(item, encoding=lambda x: x):
    indent = 2 if isinstance(item, dict) and len(item) > 1 else None
    json_bytes = json.dumps(item, indent=indent).encode()
    return encoding(json_bytes)


def digest_bytes(bytes_, algorithm=hashlib.sha256):
    checksum_bytes = algorithm(bytes_).digest()
    log.warning("Log bytes: \n[%r]", bytes_)
    return base64.encodebytes(checksum_bytes).strip()


def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256):
    content_encoded = encode_item(item, encoding)
    return digest_bytes(content_encoded, algorithm)


item = {"hello": "world"}

print("Encoding | digest-algorithm | digest-value")
print("Identity | sha256 |", digest(item))
# Encoding | digest-algorithm | digest-value
# Identity | sha256 | X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

print("Encoding | digest-algorithm | digest-value")
print("Brotli | sha256 |", digest(item, encoding=brotli.compress))
# Encoding | digest-algorithm | digest-value
# Brotli | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=

print("Encoding | digest-algorithm | digest-value")
print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512))
# Encoding | digest-algorithm | digest-value
# Identity | sha512 | b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm'
#                      '+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew=='

Changes

RFC Editor: Please remove this section before publication.¶

Authors' Addresses