jwt — JSON Web Tokens

Een kleine implementatie van de JSON Web Token (JWT)-standaard voor MicroPython. JWT is een compacte, URL-veilige container voor een JSON-payload die de uitgever ondertekent, zodat de verifieerder manipulatie en verloop kan detecteren.

Deze MicroPython-port is bewust klein gehouden:

  • Alleen HS256 (HMAC met SHA-256) wordt ondersteund. RSA-, ECDSA- en EdDSA-algoritmen zijn niet geïmplementeerd; de uitgever en de verifieerder moeten een symmetrische geheime sleutel delen.

  • De optionele exp-claim (verloop) wordt gehonoreerd. Andere geregistreerde claims (nbf, iat, iss, aud, sub, jti) worden ongewijzigd in de payload doorgegeven, maar niet gevalideerd; de applicatie controleert ze als ze er belang aan hecht.

  • Geen sleutelrotatie, JWKS of afhandeling van audience-lijsten.

Functies

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

Codeer payload naar een ondertekend JWT en geef de resulterende compacte serialisatie terug (een str van de vorm "header.payload.signature", waarbij elk segment Base64-URL-gecodeerd is).

payload

Een JSON-serialiseerbare dict met claims. Standaardclaims (exp, iat, sub, …) worden ongewijzigd doorgegeven; aangepaste applicatiesleutels zijn toegestaan.

key

Het gedeelde HMAC-geheim. bytes heeft de voorkeur; str wordt automatisch als UTF-8 gecodeerd.

algorithm

Moet "HS256" zijn (de standaardwaarde). Al het andere werpt exceptions.InvalidAlgorithmError.

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

Verifieer de handtekening van token en (indien aanwezig) de exp-claim, en geef de gedecodeerde payload-dict terug. Werpt bij elke fout een subklasse van exceptions.PyJWTError – de aanroeper vangt doorgaans de basisklasse op.

token

De compacte JWT-string die door encode() (of een willekeurige compatibele uitgever) is geproduceerd.

key

Het gedeelde HMAC-geheim. Moet overeenkomen met de sleutel die bij het coderen is gebruikt.

algorithms

De lijst met algoritmen die de aanroeper bereid is te accepteren. HS256 moet aanwezig zijn, en de alg in de header van het token moet in de lijst voorkomen. Standaardwaarde is ["HS256"].

Werpt:

Uitzonderingen

Alle uitzonderingen zijn genest onder het moduleattribuut jwt.exceptions.

exception exceptions.PyJWTError

Basisklasse voor elke JWT-fout. Vang deze op als u geen onderscheid hoeft te maken tussen de onderstaande gevallen.

exception exceptions.InvalidTokenError

Het token is structureel ongeldig – verkeerd aantal segmenten, een segment dat de Base64-decodering niet doorstaat, of JSON die niet kan worden geparseerd. Subklasse van exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError

Het algoritme van het token staat niet in de door de aanroeper geaccepteerde lijst, of de aanroeper vroeg om een ander algoritme dan HS256. Subklasse van exceptions.PyJWTError.

exception exceptions.InvalidSignatureError

De handtekening van het token komt niet overeen met de HMAC die met de opgegeven sleutel uit de header en payload is berekend. Subklasse van exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError

De exp-claim van het token ligt in het verleden. Subklasse van exceptions.PyJWTError. De wandklok-tijd van de camera moet zijn ingesteld (via ntptime.settime()) om deze controle zinvol te maken.

Voorbeeld

Een uitgifte-/verificatiecyclus met een symmetrisch geheim:

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

Hetzelfde geheim wordt gebruikt om te ondertekenen en te verifiëren, dus de verifieerder moet de sleutel bezitten die de uitgever heeft gebruikt. Voor services waarbij de camera de uitgever is (die tokens uitdeelt aan een gekoppelde telefoon), houdt u het geheim op het camerabestandssysteem en behandelt u het als elke andere langlevende referentie – zie Operaties: sleutels, verloop en probleemoplossing.

Notitie

Deze module is afhankelijk van hmac en hashlib, die beide in de camera zijn ingebouwd. Er is geen externe configuratie nodig. Sleutels mogen elke lengte hebben, maar de HMAC-constructie is het nuttigst met sleutels die minstens zo lang zijn als de SHA-256-blokgrootte (32 bytes).