Zum Hauptinhalt springen

7. Serializations (Serialisierungen)

JWS verwenden eine von zwei Serialisierungen: die JWS Compact Serialization oder die JWS JSON Serialization. Anwendungen, die diese Spezifikation verwenden, müssen spezifizieren, welche Serialisierung und welche Serialisierungsmerkmale von dieser Anwendung verwendet werden. Beispielsweise kann eine Anwendung spezifizieren, dass nur die JWS JSON Serialization verwendet wird, dass nur Unterstützung für die JWS JSON Serialization für einen einzelnen Signatur- oder MAC-Wert verwendet wird, oder dass Unterstützung für mehrere Signatur- und/oder MAC-Werte verwendet wird. JWS-Implementierungen müssen nur die Merkmale implementieren, die für die Anwendungen erforderlich sind, die sie unterstützen sollen.

7.1 JWS Compact Serialization (JWS-Kompaktserialisierung)​

Die JWS Compact Serialization repräsentiert digital signierte oder MAC-geschützte Inhalte als kompakten, URL-sicheren String. Dieser String ist:

BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload) || '.' ||
BASE64URL(JWS Signature)

Die JWS Compact Serialization unterstützt nur eine einzelne Signatur/MAC und bietet keine Syntax zur Darstellung von JWS Unprotected Header-Werten.

7.2 JWS JSON Serialization (JWS-JSON-Serialisierung)​

Die JWS JSON Serialization repräsentiert digital signierte oder MAC-geschützte Inhalte als JSON-Objekt. Diese Darstellung ist weder für Kompaktheit noch für URL-Sicherheit optimiert.

Zwei eng verwandte Syntaxen sind für die JWS JSON Serialization definiert: eine vollständig allgemeine Syntax, die die Verwendung mehrerer digitaler Signatur- und/oder MAC-Operationen zum Schutz des Inhalts ermöglicht, und eine abgeflachte Syntax, die für den Fall einer einzelnen digitalen Signatur oder eines MAC optimiert ist.

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

Die folgenden Mitglieder sind für das JSON-Objekt der obersten Ebene für die allgemeine JWS-JSON-Serialisierungssyntax definiert:

payload : Das "payload"-Mitglied muss (MUST) vorhanden sein und den Wert BASE64URL(JWS Payload) enthalten.

signatures : Der Wert des "signatures"-Mitglieds muss (MUST) ein Array von JSON-Objekten sein. Jedes Objekt repräsentiert eine Signatur oder einen MAC über den JWS Payload und den JWS Protected Header.

Die folgenden Mitglieder sind für die JSON-Objekte der Array-Elemente "signatures" definiert:

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

header : Das "header"-Mitglied muss (MUST) vorhanden sein und den Wert JWS Unprotected Header enthalten, wenn der Wert des JWS Unprotected Header nicht leer ist; andernfalls darf (MUST) es nicht vorhanden sein. Dieser Wert wird als uncodiertes JSON-Objekt dargestellt, nicht als String. Diese Header-Parameter-Werte sind nicht integritätsgeschützt.

signature : Das "signature"-Mitglied muss (MUST) vorhanden sein und den Wert BASE64URL(JWS Signature) enthalten.

Mindestens eines der "protected"- und "header"-Mitglieder muss (MUST) für jede Signatur-/MAC-Berechnung vorhanden sein, um den Wert des "alg"-Header-Parameters zu übermitteln.

Andere Mitglieder können im oben definierten JSON-Objekt vorhanden sein; wenn sie von Implementierungen, die auf sie stoßen, nicht verstanden werden, müssen (MUST) sie ignoriert werden.

Die Header-Parameter-Werte, die beim Erstellen oder Verifizieren eines individuellen Signatur- oder MAC-Werts verwendet werden, sind die Vereinigung der beiden Sätze von Header-Parameter-Werten, die vorhanden sein können: (1) der JWS Protected Header, der im "protected"-Mitglied des Array-Elements für die Signatur/MAC dargestellt wird, und (2) der JWS Unprotected Header im "header"-Mitglied des Array-Elements für die Signatur/MAC. Die Vereinigung dieser Sätze von Header-Parametern bildet den JOSE-Header. Die Header-Parameter-Namen an beiden Stellen müssen (MUST) disjunkt sein.

Jeder JWS Signature-Wert wird unter Verwendung der Parameter des entsprechenden JOSE-Header-Werts auf dieselbe Weise berechnet wie für die JWS Compact Serialization. Dies hat die wünschenswerte Eigenschaft, dass jeder im "signatures"-Array dargestellte JWS Signature-Wert derselbe ist wie der Wert, der für dieselben Parameter in der JWS Compact Serialization berechnet würde, vorausgesetzt, der Wert des JWS Protected Header für diese Signatur-/MAC-Berechnung (die die integritätsgeschützten Header-Parameter-Werte darstellt) entspricht dem in der JWS Compact Serialization verwendeten.

Zusammenfassend ist die Syntax eines JWS unter Verwendung der allgemeinen JWS-JSON-Serialisierung wie folgt:

{
 "payload":"<payload-Inhalt>",
 "signatures":[
  {"protected":"<integritätsgeschützter Header-Inhalt 1>",
   "header":<nicht integritätsgeschützter Header-Inhalt 1>,
   "signature":"<Signatur-Inhalt 1>"},
  ...
  {"protected":"<integritätsgeschützter Header-Inhalt N>",
   "header":<nicht integritätsgeschützter Header-Inhalt N>,
   "signature":"<Signatur-Inhalt N>"}]
}

Siehe Anhang A.6 für ein Beispiel eines JWS unter Verwendung der allgemeinen JWS-JSON-Serialisierungssyntax.

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

Die abgeflachte JWS-JSON-Serialisierungssyntax basiert auf der allgemeinen Syntax, flacht sie jedoch ab und optimiert sie für den Fall einer einzelnen digitalen Signatur/eines MAC. Sie flacht sie ab, indem sie das "signatures"-Mitglied entfernt und diese für die Verwendung im "signatures"-Array definierten Mitglieder (die "protected"-, "header"- und "signature"-Mitglieder) auf der Ebene des JSON-Objekts der obersten Ebene platziert (auf derselben Ebene wie das "payload"-Mitglied).

Bei Verwendung dieser Syntax darf (MUST NOT) das "signatures"-Mitglied vorhanden sein. Abgesehen von diesem Syntaxunterschied werden JWS-JSON-Serialisierungsobjekte, die die abgeflachte Syntax verwenden, genau so behandelt wie solche, die die allgemeine Syntax verwenden.

Zusammenfassend ist die Syntax eines JWS unter Verwendung der abgeflachten JWS-JSON-Serialisierung wie folgt:

{
 "payload":"<payload-Inhalt>",
 "protected":"<integritätsgeschützter Header-Inhalt>",
 "header":<nicht integritätsgeschützter Header-Inhalt>,
 "signature":"<Signatur-Inhalt>"
}

Siehe Anhang A.7 für ein Beispiel eines JWS unter Verwendung der abgeflachten JWS-JSON-Serialisierungssyntax.

Letztes Update am