jwt — JSON Web Tokens

O implementare mică a standardului JSON Web Token (JWT) pentru MicroPython. JWT este un container compact, sigur pentru URL-uri, pentru o sarcină utilă JSON pe care emitentul o semnează, astfel încât verificatorul să poată detecta falsificarea și expirarea.

Acest port MicroPython este intenționat foarte mic:

• Este acceptat doar HS256 (HMAC cu SHA-256). Algoritmii RSA / ECDSA / EdDSA nu sunt implementați; emitentul și verificatorul trebuie să partajeze o cheie secretă simetrică.

• Revendicarea opțională exp (expirare) este respectată. Alte revendicări înregistrate (nbf, iat, iss, aud, sub, jti) sunt transmise neschimbate în sarcina utilă, dar nu sunt validate; aplicația le verifică dacă îi pasă.

• Fără rotație de chei, JWKS sau gestionarea listei de audiență.

Funcții

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

Codifică payload într-un JWT semnat și returnează serializarea compactă rezultată (un str de forma "header.payload.signature", fiecare segment fiind codificat Base64-URL).

payload

Un dicționar de revendicări serializabil în JSON. Revendicările standard (exp, iat, sub, …) sunt transmise textual; cheile personalizate ale aplicației sunt permise.

key

Secretul HMAC partajat. bytes este preferat; str este codificat automat în UTF-8.

algorithm

Trebuie să fie "HS256" (valoarea implicită). Orice altceva ridică exceptions.InvalidAlgorithmError.

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

Verifică semnătura token-ului și (dacă este prezentă) revendicarea sa exp, și returnează dicționarul sarcinii utile decodificate. Ridică o subclasă a exceptions.PyJWTError la orice eșec – apelantul prinde de obicei clasa de bază.

token

Șirul JWT compact produs de encode() (sau de orice emitent compatibil).

key

Secretul HMAC partajat. Trebuie să corespundă cheii folosite la codificare.

algorithms

Lista de algoritmi pe care apelantul este dispus să îi accepte. HS256 trebuie să fie prezent, iar antetul alg al token-ului trebuie să se afle în listă. Valoarea implicită este ["HS256"].

Ridică:

• exceptions.InvalidAlgorithmError – HS256 nu se află în algorithms, sau antetul alg al token-ului este orice altceva decât HS256.

• exceptions.InvalidTokenError – token-ul este malformat (nu se împarte în trei segmente Base64-URL, sau un segment nu reușește să fie decodificat / analizat ca JSON).

• exceptions.InvalidSignatureError – semnătura nu corespunde HMAC-ului recalculat asupra antetului și sarcinii utile.

• exceptions.ExpiredSignatureError – sarcina utilă conține o revendicare exp a cărei valoare este mai mică decât timpul Unix curent. Ceasul camerei trebuie setat pentru ca această verificare să fie semnificativă; consultați ntptime.settime().

Excepții

Toate excepțiile sunt încuibate sub atributul de modul jwt.exceptions.

exception exceptions.PyJWTError

Clasa de bază pentru orice eșec JWT. Prindeți-o pe aceasta dacă nu aveți nevoie să distingeți între cazurile de mai jos.

exception exceptions.InvalidTokenError

Token-ul este invalid structural – număr greșit de segmente, un segment care eșuează la decodificarea Base64, sau JSON care nu reușește să fie analizat. Subclasă a exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError

Algoritmul token-ului nu se află în lista acceptată de apelant, sau apelantul a cerut un algoritm diferit de HS256. Subclasă a exceptions.PyJWTError.

exception exceptions.InvalidSignatureError

Semnătura token-ului nu corespunde HMAC-ului calculat din antet și sarcina utilă folosind cheia furnizată. Subclasă a exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError

Revendicarea exp a token-ului este în trecut. Subclasă a exceptions.PyJWTError. Timpul real (wall-clock) al camerei trebuie setat (prin ntptime.settime()) pentru ca această verificare să fie semnificativă.

Exemplu

Un ciclu de emitere/verificare cu secret simetric:

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

Același secret este folosit pentru a semna și a verifica, așa că verificatorul trebuie să dețină cheia folosită de emitent. Pentru serviciile în care camera este emitentul (distribuind token-uri către un telefon asociat), păstrați secretul pe sistemul de fișiere al camerei și tratați-l ca pe orice altă acreditare cu durată lungă de viață – consultați Operațiuni: chei, expirare și depanare.

Notă

Acest modul se bazează pe hmac și hashlib, ambele fiind încorporate în cameră. Nu este nevoie de nicio configurare externă. Cheile pot avea orice lungime, dar construcția HMAC este cea mai utilă cu chei cel puțin la fel de lungi ca dimensiunea blocului SHA-256 (32 de octeți).