`jwt` — JSON Web Tokens¶

Mala implementacija standarda JSON Web Token (JWT) za MicroPython. JWT je kompaktan, URL-siguran spremnik za JSON sadržaj koji izdavatelj potpisuje kako bi verifikator mogao otkriti neovlaštene izmjene i istek valjanosti.

Ovaj MicroPython port namjerno je vrlo malen:

Podržan je samo HS256 (HMAC sa SHA-256). Algoritmi RSA / ECDSA / EdDSA nisu implementirani; izdavatelj i verifikator moraju dijeliti simetrični tajni ključ.
Opcionalni zahtjev exp (istek valjanosti) se poštuje. Ostali registrirani zahtjevi (nbf, iat, iss, aud, sub, jti) prosljeđuju se nepromijenjeni u sadržaju, ali se ne provjeravaju; aplikacija ih provjerava ako joj je to važno.
Bez rotacije ključeva, JWKS-a ili rukovanja popisom primatelja.

Funkcije¶

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

Kodira payload u potpisani JWT i vraća rezultirajuću kompaktnu serijalizaciju (str oblika "header.payload.signature", pri čemu je svaki segment kodiran u Base64-URL).

payload: Rječnik zahtjeva koji se može serijalizirati u JSON. Standardni zahtjevi (exp, iat, sub, …) prosljeđuju se doslovno; dopušteni su prilagođeni aplikacijski ključevi.
key: Dijeljena HMAC tajna. bytes ima prednost; str se automatski kodira u UTF-8.
algorithm: Mora biti "HS256" (zadano). Bilo što drugo podiže exceptions.InvalidAlgorithmError.

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

Provjerava potpis token-a i (ako je prisutan) njegov zahtjev exp te vraća dekodirani rječnik sadržaja. Podiže potklasu exceptions.PyJWTError pri svakom neuspjehu – pozivatelj obično hvata osnovnu klasu.

token: Kompaktni JWT string koji proizvodi encode() (ili bilo koji kompatibilni izdavatelj).
key: Dijeljena HMAC tajna. Mora odgovarati ključu korištenom pri kodiranju.
algorithms: Popis algoritama koje je pozivatelj spreman prihvatiti. HS256 mora biti prisutan, a zaglavlje alg tokena mora biti na popisu. Zadano je ["HS256"].

Podiže:

exceptions.InvalidAlgorithmError – HS256 nije u algorithms, ili je zaglavlje alg tokena bilo što osim HS256.
exceptions.InvalidTokenError – token je neispravno oblikovan (ne dijeli se na tri Base64-URL segmenta ili se segment ne uspije dekodirati / parsirati kao JSON).
exceptions.InvalidSignatureError – potpis ne odgovara ponovno izračunatom HMAC-u nad zaglavljem i sadržajem.
exceptions.ExpiredSignatureError – sadržaj sadrži zahtjev exp čija je vrijednost manja od trenutačnog Unix vremena. Sat kamere mora biti postavljen da bi ova provjera bila smislena; vidi ntptime.settime().

Iznimke¶

Sve su iznimke ugniježđene pod atributom modula jwt.exceptions.

exception exceptions.PyJWTError¶: Osnovna klasa za svaki JWT neuspjeh. Uhvatite je ako ne trebate razlikovati slučajeve navedene u nastavku.

exception exceptions.InvalidTokenError¶: Token je strukturno neispravan – pogrešan broj segmenata, segment koji se ne uspije Base64 dekodirati ili JSON koji se ne uspije parsirati. Potklasa od exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError¶: Algoritam tokena nije na popisu prihvaćenih kod pozivatelja, ili je pozivatelj zatražio algoritam različit od HS256. Potklasa od exceptions.PyJWTError.

exception exceptions.InvalidSignatureError¶: Potpis tokena ne odgovara HMAC-u izračunatom iz zaglavlja i sadržaja pomoću dostavljenog ključa. Potklasa od exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError¶: Zahtjev exp tokena je u prošlosti. Potklasa od exceptions.PyJWTError. Vrijeme zidnog sata kamere mora biti postavljeno (putem ntptime.settime()) da bi ova provjera bila smislena.

Primjer¶

Ciklus izdavanja/provjere sa simetričnom tajnom:

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

Ista se tajna koristi za potpisivanje i provjeru, pa verifikator mora posjedovati ključ koji je izdavatelj koristio. Za usluge u kojima je kamera izdavatelj (izdaje tokene uparenom telefonu), čuvajte tajnu na datotečnom sustavu kamere i tretirajte je kao i svaku drugu dugotrajnu vjerodajnicu – vidi Operacije: ključevi, istek i rješavanje problema.

Napomena

Ovaj se modul oslanja na hmac i hashlib, koji su oba ugrađeni u kameru. Nije potrebna nikakva vanjska konfiguracija. Ključevi mogu biti bilo koje duljine, no HMAC konstrukcija najkorisnija je s ključevima barem onolike duljine kolika je veličina bloka SHA-256 (32 bajta).

jwt — JSON Web Tokens¶

Funkcije¶

Iznimke¶

Primjer¶

`jwt` — JSON Web Tokens¶