4. JOSE Header

Für ein JWS sind die Mitglieder des JOSE-Headers die Vereinigung der Mitglieder des JWS Protected Header und des JWS Unprotected Header. Der JWS Protected Header enthält Header-Parameter, die durch die JWS-Signatur oder MAC-Berechnung integritätsgeschützt sind. Der JWS Unprotected Header enthält Header-Parameter, die nicht integritätsgeschützt sind.

4.1 Registered Header Parameter Names (Registrierte Header-Parameter-Namen)

Die folgenden Header-Parameter-Namen zur Verwendung in JOSE-Headern sind im IANA-Register "JSON Web Signature and Encryption Header Parameters" registriert, das durch Abschnitt 9.1 etabliert wurde.

4.1.1 "alg" (Algorithm) Header Parameter ("alg" (Algorithmus) Header-Parameter)

Der "alg"-Header-Parameter (algorithm, Algorithmus) identifiziert den kryptografischen Algorithmus, der zur Sicherung des JWS verwendet wird. Der Wert der JWS Signature oder des JWS MAC hängt vom "alg"-Wert ab.

Der "alg"-Header-Parameter muss (MUST) im JOSE-Header vorhanden sein. Er muss (MUST) von Implementierungen verstanden und verarbeitet werden.

Eine Liste der definierten "alg"-Werte wird im IANA-Register "JSON Web Signature and Encryption Algorithms" bereitgestellt, das durch [JWA] etabliert wurde. Die anfänglichen Werte sind in Abschnitt 3.1 von [JWA] definiert. Der verwendete Wert muss entweder ein registrierter Wert oder ein Wert sein, der ein collision-resistant name (kollisionsresistenter Name) ist.

Implementierer müssen (MUST) entweder "alg"-Werte ablehnen, die sie nicht verstehen, oder sie unter Verwendung einer Richtlinie behandeln, die sie mit verstandenen Werten verknüpft. Siehe Abschnitt 10.6 für Sicherheitsüberlegungen zur Algorithmusvalidierung.

4.1.2 "jku" (JWK Set URL) Header Parameter ("jku" (JWK Set URL) Header-Parameter)

Der "jku"-Header-Parameter (JWK Set URL) ist ein URI [RFC3986], der auf eine Ressource für einen JSON-codierten JSON Web Key Set [JWK] verweist. Die dargestellten öffentlichen Schlüssel können zur Verifizierung der digitalen Signatur oder des MAC des JWS verwendet werden.

Wenn dieser Parameter verwendet wird, muss (MUST) die JWK Set-Ressource ein JSON JWK Set [JWK] darstellen. Die zum Abrufen der Ressource verwendeten Protokolle müssen (MUST) Authentifizierung und Integrität bereitstellen. Die "jku" verwendende Anwendung sollte (SHOULD) in einem Kontextdokument die Sicherheitsmechanismen spezifizieren, die zum Abrufen der Schlüssel verwendet werden.

Dieser Header-Parameter ist optional (OPTIONAL).

4.1.3 "jwk" (JSON Web Key) Header Parameter ("jwk" (JSON Web Key) Header-Parameter)

Der "jwk"-Header-Parameter (JSON Web Key) ist der öffentliche Schlüssel, der dem zur digitalen Signierung des JWS verwendeten Schlüssel entspricht. Dieser Schlüssel wird als JSON Web Key [JWK] dargestellt. Die Verwendung dieses Header-Parameters ist optional (OPTIONAL).

Wenn dieser Parameter verwendet wird, muss (MUST) der dargestellte JWK nur die JWK-Parameter enthalten, die den öffentlichen Schlüssel darstellen. Der JWK darf (MUST NOT) JWK-Parameter enthalten, die den privaten Schlüssel darstellen.

4.1.4 "kid" (Key ID) Header Parameter ("kid" (Schlüssel-ID) Header-Parameter)

Der "kid"-Header-Parameter (key ID, Schlüssel-ID) ist ein Hinweis, der angibt, welcher Schlüssel zur Sicherung des JWS verwendet wurde. Dieser Parameter ermöglicht es Ausstellern, Empfängern explizit einen Schlüsselwechsel anzuzeigen. Die Struktur des "kid"-Werts ist nicht spezifiziert. Sein Wert muss (MUST) ein case-sensitive String sein.

Die Verwendung dieses Header-Parameters ist optional (OPTIONAL).

Bei Verwendung mit JWK kann der "kid"-Wert verwendet werden, um mit einem "kid"-Parameter eines JWK übereinzustimmen.

4.1.5 "x5u" (X.509 URL) Header Parameter ("x5u" (X.509 URL) Header-Parameter)

Der "x5u"-Header-Parameter (X.509 URL) ist ein URI [RFC3986], der auf eine Ressource für das X.509-Zertifikat [RFC5280] oder die Zertifikatskette [RFC5280] verweist, die dem zur digitalen Signierung des JWS verwendeten Schlüssel entspricht. Das identifizierte Zertifikat oder die Zertifikatskette ist PEM-codiert [RFC1421].

Dieser Header-Parameter ist optional (OPTIONAL).

4.1.6 "x5c" (X.509 Certificate Chain) Header Parameter ("x5c" (X.509-Zertifikatskette) Header-Parameter)

Der "x5c"-Header-Parameter (X.509 certificate chain, X.509-Zertifikatskette) enthält die X.509-Zertifikatskette [RFC5280] oder den Zertifizierungspfad [RFC5280], die dem zur digitalen Signierung des JWS verwendeten Schlüssel entsprechen. Die Zertifikatskette wird als JSON-Array von Zertifikats-Strings dargestellt. Jeder String im Array ist ein base64-codiertes (nicht base64url-codiertes) DER PKIX-Zertifikat [RFC5280].

Das Zertifikat, das den öffentlichen Schlüssel enthält, der dem zur digitalen Signierung des JWS verwendeten Schlüssel entspricht, muss (MUST) das erste Zertifikat sein. Darauf können (MAY) zusätzliche Zertifikate folgen, wobei jedes folgende Zertifikat das vorherige zertifiziert.

Dieser Header-Parameter ist optional (OPTIONAL).

Siehe Anhang B für ein Beispiel zur Verwendung von "x5c".

4.1.7 "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter ("x5t" (X.509-Zertifikat-SHA-1-Fingerabdruck) Header-Parameter)

Der "x5t"-Header-Parameter (X.509 certificate SHA-1 thumbprint, X.509-Zertifikat-SHA-1-Fingerabdruck) ist ein base64url-codierter Thumbprint (Kurzbezeichnung für Fingerabdruck) der DER-Codierung des X.509-Zertifikats [RFC5280], das dem zur digitalen Signierung des JWS verwendeten Schlüssel entspricht. Beachten Sie, dass Zertifikatskodierungen (und damit Thumbprints) von der Reihenfolge der Zertifikatsattribute abhängig sind; siehe [RFC4945] für weitere Informationen.

Dieser Header-Parameter ist optional (OPTIONAL).

Hinweis: Dieser Parameter wird nur aus Gründen der Abwärtskompatibilität beibehalten. Implementierungen sollten stattdessen "x5t#S256" (SHA-256-Thumbprint) verwenden.

4.1.8 "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header Parameter ("x5t#S256" (X.509-Zertifikat-SHA-256-Fingerabdruck) Header-Parameter)

Der "x5t#S256"-Header-Parameter (X.509 certificate SHA-256 thumbprint, X.509-Zertifikat-SHA-256-Fingerabdruck) ist ein base64url-codierter Thumbprint der DER-Codierung des X.509-Zertifikats [RFC5280], das dem zur digitalen Signierung des JWS verwendeten Schlüssel entspricht, unter Verwendung der SHA-256-Hash-Funktion.

Dieser Header-Parameter ist optional (OPTIONAL).

4.1.9 "typ" (Type) Header Parameter ("typ" (Typ) Header-Parameter)

Der "typ"-Header-Parameter (type, Typ) wird von JWS-Anwendungen verwendet, um den Medientyp [IANA.MediaTypes] dieses vollständigen JWS-Objekts zu deklarieren. Dies ist zur Verwendung durch die Anwendung vorgesehen, wenn mehrere Inhaltstypen in derselben Datenstruktur vorhanden sein können.

Dieser Header-Parameter ist optional (OPTIONAL).

Zur Maximierung der Kompatibilität wird empfohlen (RECOMMENDED), dass JWS-Anwendungen den "application/"-Teil des Medientyps bei Verwendung von "typ" weglassen. Beispielsweise könnte ein "JWT"-Wert verwendet werden, um anzuzeigen, dass dieses Objekt ein JWT [JWT] ist, anstelle von "application/jwt".

4.1.10 "cty" (Content Type) Header Parameter ("cty" (Inhaltstyp) Header-Parameter)

Der "cty"-Header-Parameter (content type, Inhaltstyp) wird von JWS-Anwendungen verwendet, um den Medientyp [IANA.MediaTypes] des gesicherten Inhalts (des Payloads) zu deklarieren. Dies ist zur Verwendung durch die Anwendung vorgesehen, wenn mehrere Payload-Inhaltstypen vorhanden sein können.

Dieser Header-Parameter ist optional (OPTIONAL).

Im normalen Fall, in dem verschachtelte JWS oder JWE verwendet werden, wird die Verwendung dieses Header-Parameters empfohlen (RECOMMENDED). Im normalen Fall, in dem JWS nicht verschachtelt sind, wird die Verwendung dieses Header-Parameters nicht empfohlen (NOT RECOMMENDED).

Zur Maximierung der Kompatibilität wird empfohlen (RECOMMENDED), dass JWS-Anwendungen den "application/"-Teil des Medientyps bei Verwendung von "cty" weglassen.

4.1.11 "crit" (Critical) Header Parameter ("crit" (Kritisch) Header-Parameter)

Der "crit"-Header-Parameter (critical, kritisch) gibt an, dass Erweiterungen dieser Spezifikation und/oder [JWA] verwendet werden, die verstanden und verarbeitet werden müssen (MUST). Sein Wert ist ein Array, das die Namen der Header-Parameter auflistet, die im JOSE-Header vorhanden sind und diese Erweiterungen verwenden.

Wenn einer der aufgelisteten Header-Parameter-Namen vom Empfänger nicht verstanden und unterstützt wird, dann ist das JWS ungültig. Der Empfänger muss (MUST) entweder diese Header-Parameter verarbeiten oder das JWS ablehnen.

Dieser Header-Parameter ist optional (OPTIONAL).

Produzenten sollten (SHOULD) nur Erweiterungs-Header-Parameter-Namen in den "crit"-Wert aufnehmen. Header-Parameter-Namen, die durch diese Spezifikation oder [JWA] definiert sind, sollten (SHOULD NOT) aufgelistet werden.

Siehe Anhang E für einen negativen Testfall für "crit".

4.2 Public Header Parameter Names (Öffentliche Header-Parameter-Namen)

Zusätzliche Header-Parameter-Namen können von denjenigen definiert werden, die JWS produzieren und konsumieren. Um jedoch Kollisionen zu verhindern, sollten (SHOULD) alle neuen Header-Parameter-Namen entweder im IANA-Register "JSON Web Signature and Encryption Header Parameters", das durch Abschnitt 9.1 etabliert wurde, registriert werden oder ein public name (öffentlicher Name) sein: ein Wert, der einen collision-resistant name (kollisionsresistenten Namen) enthält.

In jedem Fall sollte die Definition des Header-Parameter-Namens spezifizieren, ob und wie der Header-Parameter zur Verwendung mit JWS Protected Headers, mit JWS Unprotected Headers oder beiden vorgesehen ist.

Neue Header-Parameter sollten sparsam eingeführt werden, da nicht verstandene Header-Parameter ignoriert werden müssen (MUST), es sei denn, sie sind im "crit"-Header-Parameter aufgelistet.

4.3 Private Header Parameter Names (Private Header-Parameter-Namen)

Ein Produzent und Konsument eines JWS können (MAY) vereinbaren, Header-Parameter-Namen zu verwenden, die private names (private Namen) sind: Namen, die weder im IANA-Register "JSON Web Signature and Encryption Header Parameters" (Abschnitt 9.1) registriert sind noch public names (Abschnitt 4.2) sind. Im Gegensatz zu public names sind private names kollisionsgefährdet und sollten mit Vorsicht verwendet werden.