jwt — JSON Web Tokens

A JSON Web Token (JWT) szabvány kisméretű megvalósítása a MicroPythonhoz. A JWT egy kompakt, URL-biztos tároló egy JSON adathordozóhoz, amelyet a kibocsátó aláír, így az ellenőrző észlelheti a manipulációt és a lejáratot.

Ez a MicroPython-port szándékosan apró:

• Csak a HS256 (HMAC SHA-256-tal) támogatott. Az RSA / ECDSA / EdDSA algoritmusok nincsenek megvalósítva; a kibocsátónak és az ellenőrzőnek közös szimmetrikus titkos kulccsal kell rendelkeznie.

• Az opcionális exp (lejárati) claim figyelembe van véve. A többi regisztrált claim (nbf, iat, iss, aud, sub, jti) változatlanul átmegy az adathordozóban, de nincs validálva; az alkalmazás ellenőrzi őket, ha számít neki.

• Nincs kulcsforgatás-, JWKS- vagy közönséglista-kezelés.

Függvények

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

A payload kódolása aláírt JWT-vé, és az eredményül kapott kompakt szerializáció visszaadása (egy str "header.payload.signature" formában, ahol minden szegmens Base64-URL-kódolású).

payload

Claim-ek JSON-szerializálható dict-je. A szabványos claim-ek (exp, iat, sub, …) szó szerint átmennek; az egyéni alkalmazáskulcsok megengedettek.

key

A közös HMAC titkos kulcs. A bytes az előnyben részesített; a str automatikusan UTF-8-ban kerül kódolásra.

algorithm

Értéke "HS256" kell legyen (az alapértelmezett). Bármi más exceptions.InvalidAlgorithmError kivételt vált ki.

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

A token aláírásának és (ha jelen van) exp claim-jének ellenőrzése, valamint a dekódolt adathordozó dict visszaadása. Bármilyen hiba esetén az exceptions.PyJWTError egy alosztályát váltja ki – a hívó általában az alaposztályt kapja el.

token

A encode() (vagy bármely kompatibilis kibocsátó) által előállított kompakt JWT karakterlánc.

key

A közös HMAC titkos kulcs. Meg kell egyeznie a kódoláskor használt kulccsal.

algorithms

Azon algoritmusok listája, amelyeket a hívó hajlandó elfogadni. A HS256 jelen kell legyen, és a token fejlécében lévő alg értéknek szerepelnie kell a listában. Alapértelmezetten ["HS256"].

Kiváltja:

• exceptions.InvalidAlgorithmError – a HS256 nincs az algorithms listában, vagy a token fejlécében lévő alg bármi más, mint HS256.

• exceptions.InvalidTokenError – a token hibás formátumú (nem osztható fel három Base64-URL szegmensre, vagy egy szegmens dekódolása / JSON-ként való feldolgozása sikertelen).

• exceptions.InvalidSignatureError – az aláírás nem egyezik a fejléc és az adathordozó alapján újraszámított HMAC-cel.

• exceptions.ExpiredSignatureError – az adathordozó olyan exp claim-et tartalmaz, amelynek értéke kisebb az aktuális Unix-időnél. A kamera órájának be kell lennie állítva, hogy ez az ellenőrzés értelmes legyen; lásd ntptime.settime().

Kivételek

Minden kivétel a jwt.exceptions modulattribútum alá van ágyazva.

exception exceptions.PyJWTError

Minden JWT-hiba alaposztálya. Kapja el ezt, ha nem kell megkülönböztetnie az alábbi eseteket.

exception exceptions.InvalidTokenError

A token szerkezetileg érvénytelen – helytelen számú szegmens, egy szegmens Base64-dekódolása sikertelen, vagy a JSON feldolgozása sikertelen. Az exceptions.PyJWTError alosztálya.

exception exceptions.InvalidAlgorithmError

A token algoritmusa nincs a hívó által elfogadott listában, vagy a hívó a HS256-tól eltérő algoritmust kért. Az exceptions.PyJWTError alosztálya.

exception exceptions.InvalidSignatureError

A token aláírása nem egyezik a fejléc és az adathordozó alapján a megadott kulccsal kiszámított HMAC-cel. Az exceptions.PyJWTError alosztálya.

exception exceptions.ExpiredSignatureError

A token exp claim-je a múltban van. Az exceptions.PyJWTError alosztálya. A kamera valós idejének be kell lennie állítva (a ntptime.settime() segítségével), hogy ez az ellenőrzés értelmes legyen.

Példa

Egy szimmetrikus titkos kulcsú kibocsátási/ellenőrzési ciklus:

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

Ugyanazt a titkos kulcsot használják az aláíráshoz és az ellenőrzéshez, így az ellenőrzőnek rendelkeznie kell a kibocsátó által használt kulccsal. Olyan szolgáltatások esetében, ahol a kamera a kibocsátó (tokeneket osztva ki egy párosított telefonnak), tartsa a titkos kulcsot a kamera fájlrendszerén, és kezelje úgy, mint bármely más hosszú élettartamú hitelesítő adatot – lásd Üzemeltetés: kulcsok, lejárat és hibaelhárítás.

Megjegyzés

Ez a modul a hmac és hashlib modulokra támaszkodik, amelyek mindegyike be van építve a kamerába. Nincs szükség külső konfigurációra. A kulcsok bármilyen hosszúak lehetnek, de a HMAC-konstrukció akkor a leghasznosabb, ha a kulcsok legalább olyan hosszúak, mint a SHA-256 blokkméret (32 bájt).