`jwt` — JSON Web Tokens¶

Una pequeña implementación del estándar JSON Web Token (JWT) para MicroPython. JWT es un contenedor compacto y seguro para URL de una carga JSON que el emisor firma para que el verificador pueda detectar manipulaciones y caducidad.

Este port de MicroPython es intencionadamente diminuto:

Solo se admite HS256 (HMAC con SHA-256). Los algoritmos RSA / ECDSA / EdDSA no están implementados; el emisor y el verificador deben compartir una clave secreta simétrica.
La declaración opcional exp (caducidad) se respeta. Otras declaraciones registradas (nbf, iat, iss, aud, sub, jti) se transmiten sin cambios en la carga, pero no se validan; la aplicación las comprueba si le interesan.
Sin rotación de claves, JWKS ni gestión de listas de audiencia.

Funciones¶

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

Codifica payload en un JWT firmado y devuelve la serialización compacta resultante (un str con la forma "header.payload.signature", con cada segmento codificado en Base64-URL).

payload: Un diccionario de declaraciones serializable a JSON. Las declaraciones estándar (exp, iat, sub, …) se transmiten literalmente; se permiten claves personalizadas de la aplicación.
key: El secreto HMAC compartido. Se prefiere bytes; str se codifica automáticamente en UTF-8.
algorithm: Debe ser "HS256" (el valor predeterminado). Cualquier otro valor genera exceptions.InvalidAlgorithmError.

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

Verifica la firma de token y (si está presente) su declaración exp, y devuelve el diccionario de la carga decodificada. Genera una subclase de exceptions.PyJWTError ante cualquier fallo; quien llama suele capturar la clase base.

token: La cadena JWT compacta producida por encode() (o por cualquier emisor compatible).
key: El secreto HMAC compartido. Debe coincidir con la clave utilizada en el momento de la codificación.
algorithms: La lista de algoritmos que quien llama está dispuesto a aceptar. HS256 debe estar presente, y el alg de la cabecera del token debe figurar en la lista. El valor predeterminado es ["HS256"].

Genera:

exceptions.InvalidAlgorithmError: HS256 no está en algorithms, o el alg de la cabecera del token es cualquier cosa distinta de HS256.
exceptions.InvalidTokenError: el token está mal formado (no se divide en tres segmentos Base64-URL, o un segmento no se decodifica/analiza como JSON).
exceptions.InvalidSignatureError: la firma no coincide con el HMAC recalculado sobre la cabecera y la carga.
exceptions.ExpiredSignatureError: la carga contiene una declaración exp cuyo valor es menor que la hora Unix actual. El reloj de la cámara debe estar configurado para que esta comprobación tenga sentido; consulta ntptime.settime().

Excepciones¶

Todas las excepciones están anidadas bajo el atributo de módulo jwt.exceptions.

exception exceptions.PyJWTError¶: Clase base para cada fallo de JWT. Captúrala si no necesitas distinguir entre los casos siguientes.

exception exceptions.InvalidTokenError¶: El token es estructuralmente inválido: número incorrecto de segmentos, un segmento que falla al decodificar en Base64, o JSON que no se puede analizar. Subclase de exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError¶: El algoritmo del token no está en la lista aceptada por quien llama, o quien llama solicitó un algoritmo distinto de HS256. Subclase de exceptions.PyJWTError.

exception exceptions.InvalidSignatureError¶: La firma del token no coincide con el HMAC calculado a partir de la cabecera y la carga usando la clave proporcionada. Subclase de exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError¶: La declaración exp del token está en el pasado. Subclase de exceptions.PyJWTError. La hora del reloj de la cámara debe estar configurada (mediante ntptime.settime()) para que esta comprobación tenga sentido.

Ejemplo¶

Un ciclo de emisión/verificación con secreto simétrico:

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

Se usa el mismo secreto para firmar y verificar, por lo que el verificador debe poseer la clave que utilizó el emisor. En servicios donde la cámara es el emisor (que reparte tokens a un teléfono emparejado), mantén el secreto en el sistema de archivos de la cámara y trátalo como cualquier otra credencial de larga duración; consulta Operaciones: claves, caducidad y resolución de problemas.

Nota

Este módulo se basa en hmac y hashlib, ambos integrados en la cámara. No se necesita ninguna configuración externa. Las claves pueden tener cualquier longitud, pero la construcción HMAC resulta más útil con claves al menos tan largas como el tamaño de bloque de SHA-256 (32 bytes).

jwt — JSON Web Tokens¶

Funciones¶

Excepciones¶

Ejemplo¶

`jwt` — JSON Web Tokens¶