`jwt` — JSON Web Tokens¶

Eine kleine Implementierung des JSON-Web-Token-Standards (JWT) für MicroPython. JWT ist ein kompakter, URL-sicherer Container für eine JSON-Nutzlast, die der Aussteller signiert, sodass der Prüfer Manipulationen und Ablauf erkennen kann.

Diese MicroPython-Portierung ist bewusst sehr klein gehalten:

Es wird nur HS256 (HMAC mit SHA-256) unterstützt. RSA-/ECDSA-/EdDSA-Algorithmen sind nicht implementiert; Aussteller und Prüfer müssen sich einen symmetrischen geheimen Schlüssel teilen.
Der optionale exp-Claim (Ablauf) wird beachtet. Andere registrierte Claims (nbf, iat, iss, aud, sub, jti) werden unverändert in der Nutzlast durchgereicht, aber nicht validiert; die Anwendung prüft sie, falls sie darauf Wert legt.
Keine Schlüsselrotation, kein JWKS und keine Verarbeitung von Audience-Listen.

Funktionen¶

jwt.encode(payload: dict, key: bytes | str, algorithm: str = 'HS256') → str¶

Kodiert payload in ein signiertes JWT und gibt die resultierende kompakte Serialisierung zurück (ein str der Form "header.payload.signature", wobei jedes Segment Base64-URL-kodiert ist).

payload: Ein JSON-serialisierbares Dictionary von Claims. Standard-Claims (exp, iat, sub, …) werden unverändert durchgereicht; benutzerdefinierte Anwendungsschlüssel sind zulässig.
key: Das gemeinsame HMAC-Geheimnis. bytes wird bevorzugt; str wird automatisch UTF-8-kodiert.
algorithm: Muss "HS256" sein (die Voreinstellung). Alles andere löst exceptions.InvalidAlgorithmError aus.

jwt.decode(token: str, key: bytes | str, algorithms: list = ['HS256']) → dict¶

Überprüft die Signatur von token sowie (falls vorhanden) dessen exp-Claim und gibt das dekodierte Nutzlast-Dictionary zurück. Löst bei jedem Fehler eine Unterklasse von exceptions.PyJWTError aus – der Aufrufer fängt üblicherweise die Basisklasse ab.

token: Die kompakte JWT-Zeichenkette, die von encode() (oder einem beliebigen kompatiblen Aussteller) erzeugt wurde.
key: Das gemeinsame HMAC-Geheimnis. Muss mit dem zum Zeitpunkt der Kodierung verwendeten Schlüssel übereinstimmen.
algorithms: Die Liste der Algorithmen, die der Aufrufer akzeptieren möchte. HS256 muss vorhanden sein, und das alg im Header des Tokens muss in der Liste enthalten sein. Voreinstellung ist ["HS256"].

Löst aus:

exceptions.InvalidAlgorithmError – HS256 ist nicht in algorithms enthalten, oder das alg im Header des Tokens ist etwas anderes als HS256.
exceptions.InvalidTokenError – das Token ist fehlerhaft (lässt sich nicht in drei Base64-URL-Segmente aufteilen, oder ein Segment kann nicht dekodiert / als JSON geparst werden).
exceptions.InvalidSignatureError – die Signatur stimmt nicht mit dem neu berechneten HMAC über Header und Nutzlast überein.
exceptions.ExpiredSignatureError – die Nutzlast enthält einen exp-Claim, dessen Wert kleiner als die aktuelle Unix-Zeit ist. Die Uhr der Kamera muss gestellt sein, damit diese Prüfung sinnvoll ist; siehe ntptime.settime().

Ausnahmen¶

Alle Ausnahmen sind unter dem Modulattribut jwt.exceptions verschachtelt.

exception exceptions.PyJWTError¶: Basisklasse für jeden JWT-Fehler. Fangen Sie diese ab, wenn Sie nicht zwischen den unten genannten Fällen unterscheiden müssen.

exception exceptions.InvalidTokenError¶: Das Token ist strukturell ungültig – falsche Anzahl von Segmenten, ein Segment, dessen Base64-Dekodierung fehlschlägt, oder JSON, das nicht geparst werden kann. Unterklasse von exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError¶: Der Algorithmus des Tokens ist nicht in der vom Aufrufer akzeptierten Liste enthalten, oder der Aufrufer hat einen anderen Algorithmus als HS256 angefordert. Unterklasse von exceptions.PyJWTError.

exception exceptions.InvalidSignatureError¶: Die Signatur des Tokens stimmt nicht mit dem HMAC überein, der aus Header und Nutzlast unter Verwendung des bereitgestellten Schlüssels berechnet wurde. Unterklasse von exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError¶: Der exp-Claim des Tokens liegt in der Vergangenheit. Unterklasse von exceptions.PyJWTError. Die Wanduhrzeit der Kamera muss gestellt sein (über ntptime.settime()), damit diese Prüfung sinnvoll ist.

Beispiel¶

Ein Aussteller-/Prüfzyklus mit symmetrischem Geheimnis:

import jwt
import time

SECRET = b"keep-this-out-of-source-control"

payload = {
    "sub": "kitchen-cam",
    "role": "admin",
    "exp": time.time() + 3600,                 # 1 hour from now
}

token = jwt.encode(payload, SECRET)
print("token:", token)

try:
    claims = jwt.decode(token, SECRET)
except jwt.exceptions.PyJWTError as e:
    print("rejected:", type(e).__name__)
else:
    print("subject:", claims["sub"])

Dasselbe Geheimnis wird zum Signieren und Überprüfen verwendet, sodass der Prüfer den vom Aussteller verwendeten Schlüssel besitzen muss. Bei Diensten, bei denen die Kamera der Aussteller ist (und Tokens an ein gekoppeltes Telefon ausgibt), bewahren Sie das Geheimnis auf dem Dateisystem der Kamera auf und behandeln Sie es wie jede andere langlebige Anmeldeinformation – siehe Betrieb: Schlüssel, Ablauf und Fehlerbehebung.

Bemerkung

Dieses Modul stützt sich auf hmac und hashlib, die beide in der Kamera eingebaut sind. Es ist keine externe Konfiguration erforderlich. Schlüssel können beliebig lang sein, aber die HMAC-Konstruktion ist am nützlichsten mit Schlüsseln, die mindestens so lang wie die SHA-256-Blockgröße (32 Bytes) sind.

jwt — JSON Web Tokens¶

Funktionen¶

Ausnahmen¶

Beispiel¶

`jwt` — JSON Web Tokens¶