Content-Digest header
Der HTTP-Request-Header und Response-Header Content-Digest stellt einen Digest bereit, der durch Anwendung eines Hash-Algorithmus auf den Nachrichteninhalt berechnet wird.
Empfänger können mit Content-Digest die Integrität des HTTP-Nachrichteninhalts überprüfen.
Mit dem Feld Want-Content-Digest kann ein Absender einen Content-Digest anfordern und dabei bevorzugte Hash-Algorithmen angeben.
Ein Content-Digest hängt von Content-Encoding und Content-Range ab, nicht jedoch von Transfer-Encoding.
In bestimmten Fällen kann ein Repr-Digest verwendet werden, um die Integrität von Teilnachrichten oder mehrteiligen Nachrichten anhand der vollständigen Repräsentation zu überprüfen.
Bei Bereichsanfragen hat ein Repr-Digest beispielsweise immer denselben Wert, wenn sich nur die angeforderten Bytebereiche unterscheiden. Der Content-Digest ist dagegen für jeden Teil unterschiedlich.
Wird eine Repräsentation in einer einzigen Nachricht gesendet, ist ein Content-Digest daher mit einem Repr-Digest identisch.
| Header-Typ | Request-Header, Response-Header, Repräsentations-Header |
|---|---|
| Verbotener Request-Header | Nein |
Syntax
Content-Digest: <digest-algorithm>=<digest-value>
// Multiple digest algorithms
Content-Digest: <digest-algorithm>=<digest-value>,<digest-algorithm>=<digest-value>, …
Content-Digest ist ein Wörterbuch strukturierter Felder (RFC 9651: Structured Field Values for HTTP), dessen Schlüssel <digest-algorithm> und dessen Werte <digest-value> sind.
Direktiven
<digest-algorithm>-
Der Algorithmus, mit dem ein Digest des Nachrichteninhalts erstellt wird. Nur zwei registrierte Digest-Algorithmen gelten als sicher:
sha-512undsha-256. Die registrierten unsicheren (veralteten) Digest-Algorithmen sindmd5,sha(SHA-1),unixsum,unixcksum,adler(ADLER32) undcrc32c. <digest-value>-
Der mit
<digest-algorithm>berechnete Digest des Nachrichteninhalts, Base64-kodiert und von Doppelpunkten (:, ASCII 0x3A) umschlossen. Diese Kodierung wird in der Spezifikation als Byte Sequence bezeichnet.
Beispiele
In allen Beispielen sind die Endpunkte so konfiguriert, dass sie Digest-Header ohne vorherige Anforderung senden. Ein Absender könnte optional die Felder Want-Content-Digest und Want-Repr-Digest verwenden, um einen Content-Digest oder Repr-Digest anzufordern und dabei bevorzugte Hash-Algorithmen anzugeben.
Ein SHA-256-Content-Digest in einer Antwort
Ein User-Agent fordert eine Ressource an:
GET /items/123 HTTP/1.1
Host: example.com
Der Server antwortet mit einem Content-Digest des Nachrichteninhalts, der mit dem SHA-256-Algorithmus berechnet wurde.
Der Digest wird über die exakten Bytes des Nachrichtenkörpers {"hello": "mdn"} berechnet (16 Bytes, ausdrücklich ohne abschließenden Zeilenumbruch):
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 16
Content-Digest: sha-256=:bMGjiT1wkArOzyB9ReAdpW51FV4mHlQygPXGp+TtzG4=:
{"hello": "mdn"}
Identische Content-Digest- und Repr-Digest-Werte
Ein User-Agent fordert eine Ressource an:
GET /items/123 HTTP/1.1
Host: example.com
Der Server antwortet mit einem Content-Digest und einem Repr-Digest, die mit dem SHA-256-Algorithmus berechnet wurden.
Die Felder Repr-Digest und Content-Digest haben übereinstimmende Werte, weil sie mit demselben Algorithmus über dieselben Bytes, {"hello": "mdn"} (16 Bytes), berechnet werden und in diesem Fall die gesamte Repräsentation in einer einzigen Nachricht gesendet wird:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 16
Content-Digest: sha-256=:bMGjiT1wkArOzyB9ReAdpW51FV4mHlQygPXGp+TtzG4=:
Repr-Digest: sha-256=:bMGjiT1wkArOzyB9ReAdpW51FV4mHlQygPXGp+TtzG4=:
{"hello": "mdn"}
Unterschiedliche Content-Digest- und Repr-Digest-Werte
Ein User-Agent fordert mit einer Bereichsanfrage nur einen Teil einer Ressource an:
GET /items/123 HTTP/1.1
Host: example.com
Range: bytes=0-7
Der Server gibt eine 206 Partial Content-Antwort zurück, deren Nachrichteninhalt nur die angeforderten Bytes {"hello" (8 Bytes) enthält.
Content-Digest umfasst nur diese Bytes, während Repr-Digest weiterhin die gesamte Repräsentation {"hello": "mdn"} (16 Bytes) umfasst. Daher unterscheiden sich die beiden Werte:
HTTP/1.1 206 Partial Content
Content-Type: application/json
Content-Range: bytes 0-7/16
Content-Digest: sha-256=:pKQv0IAKChzGfyfxu5TNqcnvxIzaG4XICf6NQnB1YhY=:
Repr-Digest: sha-256=:bMGjiT1wkArOzyB9ReAdpW51FV4mHlQygPXGp+TtzG4=:
Digest einer gzip-kodierten Repräsentation
In dieser Anfrage verwendet der Client den Header Accept-Encoding, um anzugeben, dass er gzip-Komprimierung akzeptiert:
GET /items/123 HTTP/1.1
Host: example.com
Accept-Encoding: gzip
Die Serverantwort enthält den Header Content-Encoding. Dieser gibt an, dass die Bytes der Nachricht aus der gzip-kodierten Repräsentation der Ressource stammen.
Der Digest wird über die gzip-kodierten Bytes statt über den ursprünglichen unkodierten Text berechnet.
Hier wird der 16 Bytes lange JSON-Körper {"hello": "mdn"} zu einer 36 Bytes langen Repräsentation gzip-komprimiert. Content-Digest und Repr-Digest werden über diese 36 Bytes berechnet (hier zur besseren Lesbarkeit hexadezimal dargestellt):
HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip
Content-Length: 36
Content-Digest: sha-256=:6Gx6u1ZhhahDLs06Zc6ZEqXxUy8RNjy18CaMucjKOFk=:
Repr-Digest: sha-256=:6Gx6u1ZhhahDLs06Zc6ZEqXxUy8RNjy18CaMucjKOFk=:
1F 8B 08 00 00 00 00 00 02 FF AB 56 CA 48 CD C9 C9 57 B2 52 50 CA 4D C9 53 AA 05 00 35 D8 1D 91 10 00 00 00
Umgang mit Content-Digest bei fehlendem Inhalt
Wird dieselbe Ressource mit der Methode HEAD statt mit GET angefordert, hat die Antwort keinen Inhalt:
HEAD /items/123 HTTP/1.1
Host: example.com
Der Wert von Repr-Digest ist derselbe wie zuvor, da er sich immer auf die vollständige Repräsentation {"hello": "mdn"} bezieht.
Der Server sendet jedoch keinen Inhalt in der Antwort und kann den Header Content-Digest weglassen:
HTTP/1.1 200 OK
Content-Type: application/json
Repr-Digest: sha-256=:bMGjiT1wkArOzyB9ReAdpW51FV4mHlQygPXGp+TtzG4=:
Statt Content-Digest bei fehlendem Inhalt wegzulassen, kann ein Server ihn ausdrücklich über eine leere Zeichenfolge berechnen.
Gemäß Abschnitt 6.3 von RFC 9530 können Empfänger dadurch überprüfen, dass kein Inhalt hinzugefügt oder entfernt wurde, statt lediglich festzustellen, dass der Header fehlt. Das ist insbesondere dann relevant, wenn der Digest durch eine HTTP-Nachrichtensignatur abgedeckt ist:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
Repr-Digest: sha-256=:bMGjiT1wkArOzyB9ReAdpW51FV4mHlQygPXGp+TtzG4=:
Ein User-Agent sendet Digests in Anfragen
Im folgenden Beispiel sendet ein User-Agent einen mit SHA-512 berechneten Digest des Nachrichteninhalts.
Der Digest wird über die exakten Bytes des Nachrichtenkörpers {"recipient":"Alex","amount":900000000} berechnet (39 Bytes, ausdrücklich ohne abschließenden Zeilenumbruch).
Da die gesamte Repräsentation in dieser einzigen Anfrage gesendet wird, haben Content-Digest und Repr-Digest denselben Wert:
POST /bank_transfer HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 39
Content-Digest: sha-512=:PlrIZYU3M76B30wGsL0h6O79BoxHTdAG+RnMPjOyECTSJCN/KnYdOrSCCWjxV3ckkyvdRmZ52//M3WbehCXcPw==:
Repr-Digest: sha-512=:PlrIZYU3M76B30wGsL0h6O79BoxHTdAG+RnMPjOyECTSJCN/KnYdOrSCCWjxV3ckkyvdRmZ52//M3WbehCXcPw==:
{"recipient":"Alex","amount":900000000}
Spezifikationen
| Spezifikation |
|---|
| Digest Fields # section-2 |
Browser-Kompatibilität
Für diesen Header ist keine Browser-Integration spezifiziert („Browser-Kompatibilität“ ist daher nicht anwendbar).
Entwickler können HTTP-Header mit fetch() setzen und auslesen, um anwendungsspezifisches Verhalten zu implementieren.
Siehe auch
- Der Header
Want-Content-Digestzum Anfordern eines Content-Digests - Die Repräsentations-Digest-Header
Repr-DigestundWant-Repr-Digest ETag- Der SDK-Leitfaden Digital Signatures for APIs verwendet
Content-Digest-Werte für digitale Signaturen in HTTP-Aufrufen (developer.ebay.com)