`jwt` — JSON Web Tokens¶

Une petite implémentation du standard JSON Web Token (JWT) pour MicroPython. Un JWT est un conteneur compact et sûr pour les URL destiné à une charge utile JSON que l’émetteur signe afin que le vérificateur puisse détecter toute altération et expiration.

Ce portage MicroPython est volontairement minimaliste :

Seul HS256 (HMAC avec SHA-256) est pris en charge. Les algorithmes RSA / ECDSA / EdDSA ne sont pas implémentés ; l’émetteur et le vérificateur doivent partager une clé secrète symétrique.
Le claim optionnel exp (expiration) est respecté. Les autres claims enregistrés (nbf, iat, iss, aud, sub, jti) sont transmis tels quels dans la charge utile mais ne sont pas validés ; l’application les vérifie si elle s’en soucie.
Aucune gestion de la rotation des clés, de JWKS ou de listes d’audiences.

Fonctions¶

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

Encode payload en un JWT signé et renvoie la sérialisation compacte résultante (une chaîne str de la forme "header.payload.signature", chaque segment étant encodé en Base64-URL).

payload: Un dictionnaire de claims sérialisable en JSON. Les claims standards (exp, iat, sub, …) sont transmis tels quels ; les clés d’application personnalisées sont autorisées.
key: Le secret HMAC partagé. bytes est préféré ; une chaîne str est automatiquement encodée en UTF-8.
algorithm: Doit être "HS256" (la valeur par défaut). Toute autre valeur lève exceptions.InvalidAlgorithmError.

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

Vérifie la signature de token et (si présent) son claim exp, puis renvoie le dictionnaire de charge utile décodé. Lève une sous-classe de exceptions.PyJWTError en cas d’échec – l’appelant attrape généralement la classe de base.

token: La chaîne JWT compacte produite par encode() (ou tout émetteur compatible).
key: Le secret HMAC partagé. Doit correspondre à la clé utilisée lors de l’encodage.
algorithms: La liste des algorithmes que l’appelant est disposé à accepter. HS256 doit être présent, et l’en-tête alg du token doit figurer dans la liste. La valeur par défaut est ["HS256"].

Lève :

exceptions.InvalidAlgorithmError – HS256 ne figure pas dans algorithms, ou l’en-tête alg du token est autre chose que HS256.
exceptions.InvalidTokenError – le token est malformé (il ne se divise pas en trois segments Base64-URL, ou un segment échoue au décodage / à l’analyse JSON).
exceptions.InvalidSignatureError – la signature ne correspond pas au HMAC recalculé sur l’en-tête et la charge utile.
exceptions.ExpiredSignatureError – la charge utile contient un claim exp dont la valeur est inférieure à l’heure Unix actuelle. L’horloge de la caméra doit être réglée pour que cette vérification soit pertinente ; voir ntptime.settime().

Exceptions¶

Toutes les exceptions sont imbriquées sous l’attribut de module jwt.exceptions.

exception exceptions.PyJWTError¶: Classe de base pour tout échec JWT. Attrapez-la si vous n’avez pas besoin de distinguer les cas ci-dessous.

exception exceptions.InvalidTokenError¶: Le token est structurellement invalide – mauvais nombre de segments, un segment qui échoue au décodage Base64, ou du JSON qui échoue à l’analyse. Sous-classe de exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError¶: L’algorithme du token ne figure pas dans la liste acceptée par l’appelant, ou l’appelant a demandé un algorithme autre que HS256. Sous-classe de exceptions.PyJWTError.

exception exceptions.InvalidSignatureError¶: La signature du token ne correspond pas au HMAC calculé à partir de l’en-tête et de la charge utile en utilisant la clé fournie. Sous-classe de exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError¶: Le claim exp du token est dans le passé. Sous-classe de exceptions.PyJWTError. L’heure de l’horloge de la caméra doit être réglée (via ntptime.settime()) pour que cette vérification soit pertinente.

Exemple¶

Un cycle d’émission/vérification à secret symétrique

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

Le même secret est utilisé pour signer et vérifier, donc le vérificateur doit détenir la clé utilisée par l’émetteur. Pour les services où la caméra est l’émetteur (distribuant des tokens à un téléphone appairé), conservez le secret sur le système de fichiers de la caméra et traitez-le comme n’importe quel autre identifiant à longue durée de vie – voir Exploitation : clés, expiration et dépannage.

Note

Ce module s’appuie sur hmac et hashlib, tous deux intégrés à la caméra. Aucune configuration externe n’est nécessaire. Les clés peuvent être de n’importe quelle longueur, mais la construction HMAC est plus utile avec des clés au moins aussi longues que la taille de bloc de SHA-256 (32 octets).

jwt — JSON Web Tokens¶

Fonctions¶

Exceptions¶

Exemple¶

`jwt` — JSON Web Tokens¶