jwt — JSON Web Tokens

Malá implementace standardu JSON Web Token (JWT) pro MicroPython. JWT je kompaktní, URL-safe kontejner pro JSON payload, který vydavatel podepíše, aby ověřovatel mohl detekovat manipulaci a vypršení platnosti.

Tento port pro MicroPython je záměrně velmi malý:

  • Podporován je pouze HS256 (HMAC se SHA-256). Algoritmy RSA / ECDSA / EdDSA implementovány nejsou; vydavatel a ověřovatel musí sdílet symetrický tajný klíč.

  • Volitelný nárok exp (expirace) je respektován. Ostatní registrované nároky (nbf, iat, iss, aud, sub, jti) jsou v payloadu předány beze změny, ale nejsou validovány; aplikace je zkontroluje, pokud na nich záleží.

  • Žádná rotace klíčů, JWKS ani zpracování seznamu příjemců.

Funkce

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

Zakóduje payload do podepsaného JWT a vrátí výslednou kompaktní serializaci (str ve tvaru "header.payload.signature", kde každý segment je zakódován pomocí Base64-URL).

payload

JSON-serializovatelný dict nároků. Standardní nároky (exp, iat, sub, …) jsou předány beze změny; vlastní aplikační klíče jsou povoleny.

key

Sdílený HMAC tajný klíč. Preferuje se bytes; str je automaticky zakódován jako UTF-8.

algorithm

Musí být "HS256" (výchozí). Cokoli jiného vyvolá exceptions.InvalidAlgorithmError.

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

Ověří podpis token a (pokud je přítomen) jeho nárok exp a vrátí dekódovaný payload jako dict. Při jakémkoli selhání vyvolá podtřídu exceptions.PyJWTError – volající obvykle zachytává základní třídu.

token

Kompaktní JWT řetězec vytvořený pomocí encode() (nebo jakýmkoli kompatibilním vydavatelem).

key

Sdílený HMAC tajný klíč. Musí odpovídat klíči použitému při kódování.

algorithms

Seznam algoritmů, které je volající ochoten přijmout. HS256 musí být přítomen a hlavička tokenu alg musí být v seznamu. Výchozí hodnota je ["HS256"].

Vyvolává:

Výjimky

Všechny výjimky jsou vnořeny pod atributem modulu jwt.exceptions.

exception exceptions.PyJWTError

Základní třída pro každé selhání JWT. Zachyťte ji, pokud nepotřebujete rozlišovat mezi níže uvedenými případy.

exception exceptions.InvalidTokenError

Token je strukturálně neplatný – špatný počet segmentů, segment, který selže při Base64 dekódování, nebo JSON, který se nepodaří naparsovat. Podtřída exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError

Algoritmus tokenu není v seznamu přijímaném volajícím, nebo volající požádal o jiný algoritmus než HS256. Podtřída exceptions.PyJWTError.

exception exceptions.InvalidSignatureError

Podpis tokenu neodpovídá HMAC vypočtenému z hlavičky a payloadu pomocí dodaného klíče. Podtřída exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError

Nárok exp tokenu je v minulosti. Podtřída exceptions.PyJWTError. Aby tato kontrola měla smysl, musí být nastaven reálný čas kamery (pomocí ntptime.settime()).

Příklad

Cyklus vydání/ověření se symetrickým tajným klíčem:

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"])

K podepsání i ověření se používá stejný tajný klíč, takže ověřovatel musí mít klíč, který použil vydavatel. U služeb, kde je vydavatelem kamera (vydávající tokeny spárovanému telefonu), uchovávejte tajný klíč na souborovém systému kamery a zacházejte s ním jako s každým jiným dlouhodobým přihlašovacím údajem – viz Provoz: klíče, expirace a řešení potíží.

Poznámka

Tento modul se spoléhá na hmac a hashlib, které jsou oba vestavěné v kameře. Žádná externí konfigurace není potřeba. Klíče mohou být libovolné délky, ale HMAC konstrukce je nejužitečnější s klíči alespoň tak dlouhými, jako je velikost bloku SHA-256 (32 bajtů).