`jwt` — JSON Web Token¶

Una piccola implementazione dello standard JSON Web Token (JWT) per MicroPython. JWT è un contenitore compatto e URL-safe per un payload JSON che l’emittente firma in modo che il verificatore possa rilevare manomissioni e scadenze.

Questo port per MicroPython è volutamente minimale:

È supportato solo HS256 (HMAC con SHA-256). Gli algoritmi RSA / ECDSA / EdDSA non sono implementati; l’emittente e il verificatore devono condividere una chiave segreta simmetrica.
Il claim opzionale exp (scadenza) viene rispettato. Gli altri claim registrati (nbf, iat, iss, aud, sub, jti) vengono trasferiti invariati nel payload ma non validati; l’applicazione li controlla se lo ritiene necessario.
Nessuna gestione di rotazione delle chiavi, JWKS o elenco di audience.

Funzioni¶

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

Codifica payload in un JWT firmato e restituisce la serializzazione compatta risultante (uno str della forma "header.payload.signature", con ogni segmento codificato in Base64-URL).

payload: Un dict di claim serializzabile in JSON. I claim standard (exp, iat, sub, …) vengono trasferiti verbatim; sono consentite chiavi applicative personalizzate.
key: Il segreto HMAC condiviso. È preferibile bytes; str viene codificato automaticamente in UTF-8.
algorithm: Deve essere "HS256" (il valore predefinito). Qualsiasi altro valore solleva exceptions.InvalidAlgorithmError.

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

Verifica la firma di token e (se presente) il suo claim exp, e restituisce il dict del payload decodificato. Solleva una sottoclasse di exceptions.PyJWTError in caso di qualsiasi errore; il chiamante di solito intercetta la classe base.

token: La stringa JWT compatta prodotta da encode() (o da qualsiasi emittente compatibile).
key: Il segreto HMAC condiviso. Deve corrispondere alla chiave usata al momento della codifica.
algorithms: L’elenco degli algoritmi che il chiamante è disposto ad accettare. HS256 deve essere presente, e l”alg nell’header del token deve essere nell’elenco. Il valore predefinito è ["HS256"].

Solleva:

exceptions.InvalidAlgorithmError – HS256 non è in algorithms, oppure l”alg nell’header del token è qualcosa di diverso da HS256.
exceptions.InvalidTokenError – il token è malformato (non si suddivide in tre segmenti Base64-URL, oppure un segmento non riesce a essere decodificato / analizzato come JSON).
exceptions.InvalidSignatureError – la firma non corrisponde all’HMAC ricalcolato sull’header e sul payload.
exceptions.ExpiredSignatureError – il payload contiene un claim exp il cui valore è inferiore all’ora Unix corrente. L’orologio della camera deve essere impostato perché questo controllo sia significativo; vedi ntptime.settime().

Eccezioni¶

Tutte le eccezioni sono annidate sotto l’attributo del modulo jwt.exceptions.

exception exceptions.PyJWTError¶: Classe base per ogni errore JWT. Intercetta questa se non hai bisogno di distinguere tra i casi seguenti.

exception exceptions.InvalidTokenError¶: Il token è strutturalmente non valido: numero errato di segmenti, un segmento che non riesce nella decodifica Base64, o JSON che non riesce a essere analizzato. Sottoclasse di exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError¶: L’algoritmo del token non è nell’elenco accettato dal chiamante, oppure il chiamante ha richiesto un algoritmo diverso da HS256. Sottoclasse di exceptions.PyJWTError.

exception exceptions.InvalidSignatureError¶: La firma del token non corrisponde all’HMAC calcolato dall’header e dal payload usando la chiave fornita. Sottoclasse di exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError¶: Il claim exp del token è nel passato. Sottoclasse di exceptions.PyJWTError. L’ora dell’orologio di sistema della camera deve essere impostata (tramite ntptime.settime()) perché questo controllo sia significativo.

Esempio¶

Un ciclo di emissione/verifica con segreto simmetrico:

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

Lo stesso segreto viene usato per firmare e verificare, quindi il verificatore deve possedere la chiave usata dall’emittente. Per i servizi in cui la camera è l’emittente (che distribuisce token a un telefono accoppiato), mantieni il segreto nel filesystem della camera e trattalo come qualsiasi altra credenziale a lunga durata; vedi Operazioni: chiavi, scadenza e risoluzione dei problemi.

Nota

Questo modulo si basa su hmac e hashlib, entrambi integrati nella camera. Non è necessaria alcuna configurazione esterna. Le chiavi possono essere di qualsiasi lunghezza, ma la costruzione HMAC è più utile con chiavi lunghe almeno quanto la dimensione del blocco di SHA-256 (32 byte).

jwt — JSON Web Token¶

Funzioni¶

Eccezioni¶

Esempio¶

`jwt` — JSON Web Token¶