`jwt` — JSON Web Tokens¶

Uma pequena implementação do padrão JSON Web Token (JWT) para o MicroPython. JWT é um contêiner compacto e seguro para URLs que armazena uma carga útil JSON que o emissor assina para que o verificador possa detectar adulterações e expiração.

Esta port para MicroPython é intencionalmente minúscula:

Apenas HS256 (HMAC com SHA-256) é suportado. Algoritmos RSA / ECDSA / EdDSA não estão implementados; o emissor e o verificador devem compartilhar uma chave secreta simétrica.
A reivindicação opcional exp (expiração) é respeitada. Outras reivindicações registradas (nbf, iat, iss, aud, sub, jti) são passadas adiante sem alteração na carga útil, mas não são validadas; a aplicação as verifica se lhe interessar.
Sem manipulação de rotação de chaves, JWKS ou lista de audiência.

Funções¶

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

Codifica payload em um JWT assinado e retorna a serialização compacta resultante (uma str no formato "header.payload.signature", com cada segmento codificado em Base64-URL).

payload: Um dict de reivindicações serializável em JSON. Reivindicações padrão (exp, iat, sub, …) são passadas adiante literalmente; chaves personalizadas da aplicação são permitidas.
key: O segredo HMAC compartilhado. bytes é preferível; str é codificado automaticamente em UTF-8.
algorithm: Deve ser "HS256" (o padrão). Qualquer outro valor levanta exceptions.InvalidAlgorithmError.

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

Verifica a assinatura de token e (se presente) sua reivindicação exp, e retorna o dict da carga útil decodificada. Levanta uma subclasse de exceptions.PyJWTError em qualquer falha – o chamador geralmente captura a classe base.

token: A string JWT compacta produzida por encode() (ou por qualquer emissor compatível).
key: O segredo HMAC compartilhado. Deve corresponder à chave usada no momento da codificação.
algorithms: A lista de algoritmos que o chamador está disposto a aceitar. HS256 deve estar presente, e o alg do cabeçalho do token deve estar na lista. O padrão é ["HS256"].

Levanta:

exceptions.InvalidAlgorithmError – HS256 não está em algorithms, ou o alg do cabeçalho do token é qualquer coisa diferente de HS256.
exceptions.InvalidTokenError – o token está malformado (não se divide em três segmentos Base64-URL, ou um segmento falha ao decodificar / analisar como JSON).
exceptions.InvalidSignatureError – a assinatura não corresponde ao HMAC recalculado sobre o cabeçalho e a carga útil.
exceptions.ExpiredSignatureError – a carga útil contém uma reivindicação exp cujo valor é menor que o tempo Unix atual. O relógio da câmera deve estar ajustado para que essa verificação seja significativa; veja ntptime.settime().

Exceções¶

Todas as exceções estão aninhadas sob o atributo de módulo jwt.exceptions.

exception exceptions.PyJWTError¶: Classe base para toda falha de JWT. Capture esta se você não precisar distinguir entre os casos abaixo.

exception exceptions.InvalidTokenError¶: O token é estruturalmente inválido – número errado de segmentos, um segmento que falha na decodificação Base64, ou JSON que falha na análise. Subclasse de exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError¶: O algoritmo do token não está na lista aceita pelo chamador, ou o chamador solicitou um algoritmo diferente de HS256. Subclasse de exceptions.PyJWTError.

exception exceptions.InvalidSignatureError¶: A assinatura do token não corresponde ao HMAC calculado a partir do cabeçalho e da carga útil usando a chave fornecida. Subclasse de exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError¶: A reivindicação exp do token está no passado. Subclasse de exceptions.PyJWTError. O horário do relógio da câmera deve estar ajustado (via ntptime.settime()) para que essa verificação seja significativa.

Exemplo¶

Um ciclo de emissão/verificação com segredo 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"])

O mesmo segredo é usado para assinar e verificar, então o verificador deve possuir a chave que o emissor usou. Para serviços em que a câmera é a emissora (distribuindo tokens para um telefone pareado), mantenha o segredo no sistema de arquivos da câmera e trate-o como qualquer outra credencial de longa duração – veja Operações: chaves, expiração e solução de problemas.

Nota

Este módulo depende de hmac e hashlib, ambos integrados à câmera. Nenhuma configuração externa é necessária. As chaves podem ter qualquer comprimento, mas a construção HMAC é mais útil com chaves pelo menos tão longas quanto o tamanho do bloco do SHA-256 (32 bytes).

jwt — JSON Web Tokens¶

Funções¶

Exceções¶

Exemplo¶

`jwt` — JSON Web Tokens¶