`jwt` — JSON Web Tokens¶

Uma implementação compacta do padrão JSON Web Token (JWT) para MicroPython. O JWT é um contentor compacto e seguro para URLs que transporta um payload JSON assinado pelo emissor, permitindo ao verificador detetar adulterações e expiração.

Esta versão para MicroPython é intencionalmente reduzida:

Apenas o algoritmo HS256 (HMAC com SHA-256) é suportado. Os algoritmos RSA / ECDSA / EdDSA não estão implementados; o emissor e o verificador têm de partilhar uma chave secreta simétrica.
A afirmação opcional exp (expiração) é respeitada. Outras afirmações registadas (nbf, iat, iss, aud, sub, jti) são transmitidas sem alteração no payload, mas não são validadas; a aplicação verifica-as se assim o entender.
Sem rotação de chaves, JWKS, nem tratamento de listas de audiências.

Funções¶

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

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

payload: Um dict de afirmações serializável em JSON. As afirmações padrão (exp, iat, sub, …) são transmitidas verbatim; são permitidas chaves de aplicação personalizadas.
key: O segredo HMAC partilhado. Prefere-se bytes; str é codificado automaticamente em UTF-8.
algorithm: Deve ser "HS256" (o valor predefinido). 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) a sua afirmação exp, e devolve o dict do payload descodificado. Levanta uma subclasse de exceptions.PyJWTError em caso de qualquer falha – o chamador normalmente apanha a classe base.

token: A string JWT compacta produzida por encode() (ou qualquer emissor compatível).
key: O segredo HMAC partilhado. Deve corresponder à chave utilizada 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 constar da lista. O valor predefinido é ["HS256"].

Levanta:

exceptions.InvalidAlgorithmError – HS256 não consta de algorithms, ou o alg do cabeçalho do token é diferente de HS256.
exceptions.InvalidTokenError – o token está malformado (não se divide em três segmentos Base64-URL, ou um segmento falha na descodificação / análise como JSON).
exceptions.InvalidSignatureError – a assinatura não corresponde ao HMAC recalculado sobre o cabeçalho e o payload.
exceptions.ExpiredSignatureError – o payload contém uma afirmação exp cujo valor é inferior ao tempo Unix atual. O relógio da câmara deve estar definido para que esta verificação seja significativa; consulte ntptime.settime().

Exceções¶

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

exception exceptions.PyJWTError¶: Classe base para todas as falhas JWT. Utilize-a se não precisar de distinguir entre os casos abaixo.

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

exception exceptions.InvalidAlgorithmError¶: O algoritmo do token não consta da lista aceite 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 do payload com a chave fornecida. Subclasse de exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError¶: A afirmação exp do token está no passado. Subclasse de exceptions.PyJWTError. O tempo de relógio de parede da câmara deve estar definido (via ntptime.settime()) para que esta 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 é utilizado para assinar e verificar, pelo que o verificador tem de possuir a chave utilizada pelo emissor. Para serviços em que a câmara é o emissor (distribuindo tokens a um telemóvel associado), mantenha o segredo no sistema de ficheiros da câmara e trate-o como qualquer outra credencial de longa duração – consulte Operações: chaves, expiração e resolução de problemas.

Nota

Este módulo depende de hmac e hashlib, ambos incorporados na câmara. Não é necessária qualquer configuração externa. 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 SHA-256 (32 bytes).

jwt — JSON Web Tokens¶

Funções¶

Exceções¶

Exemplo¶

`jwt` — JSON Web Tokens¶