Zum Hauptinhalt springen

7. Serializations (Serialisierungen)

JWEs verwenden eine von zwei Serialisierungen: die JWE Compact Serialization oder die JWE JSON Serialization. Anwendungen, die diese Spezifikation verwenden, müssen angeben, welche Serialisierung und welche Serialisierungsfunktionen für diese Anwendung verwendet werden. Beispielsweise können Anwendungen angeben, dass nur die JWE JSON Serialization verwendet wird, dass nur die JWE JSON Serialization-Unterstützung für einen einzelnen Empfänger verwendet wird oder dass Unterstützung für mehrere Empfänger verwendet wird. JWE-Implementierungen müssen nur die Funktionen implementieren, die für die Anwendungen erforderlich sind, für die sie zur Unterstützung entwickelt wurden.

7.1 JWE Compact Serialization (JWE Compact-Serialisierung)​

Die JWE Compact Serialization stellt verschlüsselten Inhalt als kompakte, URL-sichere Zeichenfolge dar. Diese Zeichenfolge ist:

BASE64URL(UTF8(JWE Protected Header)) || '.' ||
BASE64URL(JWE Encrypted Key) || '.' ||
BASE64URL(JWE Initialization Vector) || '.' ||
BASE64URL(JWE Ciphertext) || '.' ||
BASE64URL(JWE Authentication Tag)

Nur ein Empfänger wird von der JWE Compact Serialization unterstützt und sie bietet keine Syntax zur Darstellung von JWE Shared Unprotected Header, JWE Per-Recipient Unprotected Header oder JWE AAD-Werten.

7.2 JWE JSON Serialization (JWE JSON-Serialisierung)​

Die JWE JSON Serialization stellt verschlüsselten Inhalt als JSON-Objekt dar. Diese Darstellung ist weder für Kompaktheit optimiert noch URL-sicher.

Für die JWE JSON Serialization sind zwei eng verwandte Syntaxen definiert: eine vollständig generische Syntax, mit der Inhalt für mehr als einen Empfänger verschlüsselt werden kann, und eine abgeflachte Syntax, die für den Fall eines einzelnen Empfängers optimiert ist.

7.2.1 General JWE JSON Serialization Syntax (Allgemeine JWE JSON-Serialisierungssyntax)​

Die folgenden Mitglieder sind für die Verwendung in JSON-Objekten der obersten Ebene definiert, die für die vollständig generische JWE JSON-Serialisierungssyntax verwendet werden:

protected : Das "protected"-Mitglied muss (MUST) vorhanden sein und den Wert BASE64URL(UTF8(JWE Protected Header)) enthalten, wenn der JWE Protected Header-Wert nicht leer ist; andernfalls muss (MUST) es fehlen. Diese Header-Parameterwerte sind integritätsgeschützt.

unprotected : Das "unprotected"-Mitglied muss (MUST) vorhanden sein und den Wert JWE Shared Unprotected Header enthalten, wenn der JWE Shared Unprotected Header-Wert nicht leer ist; andernfalls muss (MUST) es fehlen. Dieser Wert wird als nicht codiertes JSON-Objekt dargestellt, nicht als Zeichenfolge. Diese Header-Parameterwerte sind nicht integritätsgeschützt.

iv : Das "iv"-Mitglied muss (MUST) vorhanden sein und den Wert BASE64URL(JWE Initialization Vector) enthalten, wenn der JWE Initialization Vector-Wert nicht leer ist; andernfalls muss (MUST) es fehlen.

aad : Das "aad"-Mitglied muss (MUST) vorhanden sein und den Wert BASE64URL(JWE AAD) enthalten, wenn der JWE AAD-Wert nicht leer ist; andernfalls muss (MUST) es fehlen. Ein JWE AAD-Wert kann einbezogen werden, um einen base64url-codierten Wert bereitzustellen, der integritätsgeschützt, aber nicht verschlüsselt ist.

ciphertext : Das "ciphertext"-Mitglied muss (MUST) vorhanden sein und den Wert BASE64URL(JWE Ciphertext) enthalten.

tag : Das "tag"-Mitglied muss (MUST) vorhanden sein und den Wert BASE64URL(JWE Authentication Tag) enthalten, wenn der JWE Authentication Tag-Wert nicht leer ist; andernfalls muss (MUST) es fehlen.

recipients : Der "recipients"-Mitgliedswert muss (MUST) ein Array von JSON-Objekten sein. Jedes Objekt enthält Informationen, die für einen einzelnen Empfänger spezifisch sind. Dieses Mitglied muss (MUST) mit genau einem Array-Element pro Empfänger vorhanden sein, selbst wenn einige oder alle Array-Elementwerte das leere JSON-Objekt "" sind (was auftreten kann, wenn alle Header-Parameterwerte zwischen allen Empfängern geteilt werden und kein verschlüsselter Schlüssel verwendet wird, wie bei direkter Verschlüsselung).

Die folgenden Mitglieder sind für die Verwendung in den JSON-Objekten definiert, die Elemente des "recipients"-Arrays sind:

header : Das "header"-Mitglied muss (MUST) vorhanden sein und den Wert JWE Per-Recipient Unprotected Header enthalten, wenn der JWE Per-Recipient Unprotected Header-Wert nicht leer ist; andernfalls muss (MUST) es fehlen. Dieser Wert wird als nicht codiertes JSON-Objekt dargestellt, nicht als Zeichenfolge. Diese Header-Parameterwerte sind nicht integritätsgeschützt.

encrypted_key : Das "encrypted_key"-Mitglied muss (MUST) vorhanden sein und den Wert BASE64URL(JWE Encrypted Key) enthalten, wenn der JWE Encrypted Key-Wert nicht leer ist; andernfalls muss (MUST) es fehlen.

Mindestens eines der Mitglieder "header", "protected" und "unprotected" muss (MUST) vorhanden sein, damit "alg"- und "enc"-Header-Parameterwerte für jede Empfängerberechnung übermittelt werden.

Zusätzliche Mitglieder können in beiden oben definierten JSON-Objekten vorhanden sein; wenn Implementierungen, die auf sie stoßen, sie nicht verstehen, müssen (MUST) sie ignoriert werden.

Einige Header-Parameter, einschließlich des "alg"-Parameters, können zwischen allen Empfängerberechnungen geteilt werden. Header-Parameterwerte im JWE Protected Header und JWE Shared Unprotected Header-Werten werden zwischen allen Empfängern geteilt.

Die Header-Parameterwerte, die beim Erstellen oder Validieren von empfängerspezifischem Chiffretext und Authentication Tag-Werten verwendet werden, sind die Vereinigung der drei Sätze von Header-Parameterwerten, die vorhanden sein können: (1) der JWE Protected Header, der im "protected"-Mitglied dargestellt wird, (2) der JWE Shared Unprotected Header, der im "unprotected"-Mitglied dargestellt wird, und (3) der JWE Per-Recipient Unprotected Header, der im "header"-Mitglied des Array-Elements des Empfängers dargestellt wird. Die Vereinigung dieser Sätze von Header-Parametern bildet den JOSE-Header. Die Header-Parameternamen an den drei Standorten müssen (MUST) disjunkt sein.

Jeder JWE Encrypted Key-Wert wird unter Verwendung der Parameter des entsprechenden JOSE-Header-Werts auf die gleiche Weise wie für die JWE Compact Serialization berechnet. Dies hat die wünschenswerte Eigenschaft, dass jeder JWE Encrypted Key-Wert im "recipients"-Array identisch mit dem Wert ist, der für dieselben Parameter in einer JWE Compact Serialization berechnet worden wäre. Ebenso entsprechen die JWE Ciphertext- und JWE Authentication Tag-Werte denen, die für die JWE Compact Serialization erzeugt wurden, vorausgesetzt, dass der JWE Protected Header-Wert (der die integritätsgeschützten Header-Parameterwerte darstellt) mit dem in der JWE Compact Serialization verwendeten übereinstimmt.

Alle Empfänger verwenden dieselben JWE Protected Header-, JWE Initialization Vector-, JWE Ciphertext- und JWE Authentication Tag-Werte, wenn vorhanden, was zu potenziell erheblichen Platzeinsparungen führt, wenn die Nachricht groß ist. Daher müssen (MUST) alle Header-Parameter, die die Behandlung des Klartextwerts spezifizieren, für alle Empfänger gleich sein. Dies bedeutet hauptsächlich, dass der "enc" (Verschlüsselungsalgorithmus)-Header-Parameterwert im JOSE-Header für jeden Empfänger und alle Parameter dieses Algorithmus gleich sein müssen (MUST).

Zusammenfassend lautet die Syntax eines JWE unter Verwendung der allgemeinen JWE JSON-Serialisierung wie folgt:

{
 "protected":"<integrity-protected shared header contents>",
 "unprotected":<non-integrity-protected shared header contents>,
 "recipients":[
  {"header":<per-recipient unprotected header 1 contents>,
   "encrypted_key":"<encrypted key 1 contents>"},
  ...
  {"header":<per-recipient unprotected header N contents>,
   "encrypted_key":"<encrypted key N contents>"}],
 "aad":"<additional authenticated data contents>",
 "iv":"<initialization vector contents>",
 "ciphertext":"<ciphertext contents>",
 "tag":"<authentication tag contents>"
}

Siehe Anhang A.4 für ein Beispiel-JWE unter Verwendung der allgemeinen JWE JSON-Serialisierungssyntax.

7.2.2 Flattened JWE JSON Serialization Syntax (Abgeflachte JWE JSON-Serialisierungssyntax)​

Die abgeflachte JWE JSON-Serialisierungssyntax basiert auf der allgemeinen Syntax, flacht sie jedoch ab und optimiert sie für den Fall eines einzelnen Empfängers. Sie flacht sie ab, indem sie das "recipients"-Mitglied entfernt und stattdessen die Mitglieder, die für die Verwendung im "recipients"-Array definiert sind (die "header"- und "encrypted_key"-Mitglieder), im JSON-Objekt der obersten Ebene platziert (auf derselben Ebene wie das "ciphertext"-Mitglied).

Das "recipients"-Mitglied darf (MUST NOT) bei Verwendung dieser Syntax nicht vorhanden sein. Abgesehen von diesem Syntaxunterschied werden JWE JSON-Serialisierungsobjekte, die die abgeflachte Syntax verwenden, identisch mit denen verarbeitet, die die allgemeine Syntax verwenden.

Zusammenfassend lautet die Syntax eines JWE unter Verwendung der abgeflachten JWE JSON-Serialisierung wie folgt:

{
 "protected":"<integrity-protected header contents>",
 "unprotected":<non-integrity-protected header contents>,
 "header":<more non-integrity-protected header contents>,
 "encrypted_key":"<encrypted key contents>",
 "aad":"<additional authenticated data contents>",
 "iv":"<initialization vector contents>",
 "ciphertext":"<ciphertext contents>",
 "tag":"<authentication tag contents>"
}

Beachten Sie, dass bei Verwendung der abgeflachten Syntax, genau wie bei Verwendung der allgemeinen Syntax, alle nicht geschützten Header-Parameterwerte entweder im "unprotected"-Mitglied oder im "header"-Mitglied oder in beiden residieren können.

Siehe Anhang A.5 für ein Beispiel-JWE unter Verwendung der abgeflachten JWE JSON-Serialisierungssyntax.

Letztes Update am