`jwt` — JSON Web Tokens¶

En liten implementation av standarden JSON Web Token (JWT) för MicroPython. JWT är en kompakt, URL-säker behållare för en JSON-nyttolast som utfärdaren signerar så att verifieraren kan upptäcka manipulering och förfall.

Denna MicroPython-port är avsiktligt minimal:

Endast HS256 (HMAC med SHA-256) stöds. Algoritmerna RSA / ECDSA / EdDSA är inte implementerade; utfärdaren och verifieraren måste dela en symmetrisk hemlig nyckel.
Det valfria anspråket exp (förfall) respekteras. Övriga registrerade anspråk (nbf, iat, iss, aud, sub, jti) skickas vidare oförändrade i nyttolasten men valideras inte; applikationen kontrollerar dem om den bryr sig.
Ingen hantering av nyckelrotation, JWKS eller mottagarlistor.

Funktioner¶

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

Koda payload till en signerad JWT och returnera den resulterande kompakta serialiseringen (en str av formen "header.payload.signature", där varje segment är Base64-URL-kodat).

payload: En JSON-serialiserbar dict med anspråk. Standardanspråk (exp, iat, sub, …) skickas vidare ordagrant; anpassade applikationsnycklar är tillåtna.
key: Den delade HMAC-hemligheten. bytes föredras; str UTF-8-kodas automatiskt.
algorithm: Måste vara "HS256" (standardvärdet). Allt annat ger exceptions.InvalidAlgorithmError.

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

Verifiera signaturen för token och (om det finns) dess exp-anspråk, och returnera den avkodade nyttolasts-dicten. Ger en subklass av exceptions.PyJWTError vid varje fel – anroparen fångar vanligtvis basklassen.

token: Den kompakta JWT-strängen som produceras av encode() (eller någon kompatibel utfärdare).
key: Den delade HMAC-hemligheten. Måste matcha nyckeln som användes vid kodningen.
algorithms: Listan över algoritmer som anroparen är villig att acceptera. HS256 måste finnas med, och tokenens header-alg måste finnas i listan. Standardvärdet är ["HS256"].

Ger:

exceptions.InvalidAlgorithmError – HS256 finns inte i algorithms, eller tokenens header-alg är något annat än HS256.
exceptions.InvalidTokenError – tokenen är felformad (delas inte upp i tre Base64-URL-segment, eller ett segment misslyckas med att avkodas / tolkas som JSON).
exceptions.InvalidSignatureError – signaturen matchar inte den omräknade HMAC:en över headern och nyttolasten.
exceptions.ExpiredSignatureError – nyttolasten innehåller ett exp-anspråk vars värde är mindre än den aktuella Unix-tiden. Kamerans klocka måste vara inställd för att denna kontroll ska vara meningsfull; se ntptime.settime().

Undantag¶

Alla undantag är nästlade under modulattributet jwt.exceptions.

exception exceptions.PyJWTError¶: Basklass för varje JWT-fel. Fånga detta om du inte behöver skilja mellan fallen nedan.

exception exceptions.InvalidTokenError¶: Tokenen är strukturellt ogiltig – fel antal segment, ett segment som misslyckas med Base64-avkodning, eller JSON som misslyckas med att tolkas. Subklass till exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError¶: Tokenens algoritm finns inte i listan som anroparen accepterar, eller så bad anroparen om en annan algoritm än HS256. Subklass till exceptions.PyJWTError.

exception exceptions.InvalidSignatureError¶: Tokenens signatur matchar inte den HMAC som beräknats från headern och nyttolasten med den tillhandahållna nyckeln. Subklass till exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError¶: Tokenens exp-anspråk ligger i det förflutna. Subklass till exceptions.PyJWTError. Kamerans realtidsklocka måste vara inställd (via ntptime.settime()) för att denna kontroll ska vara meningsfull.

Exempel¶

En utfärdnings-/verifieringscykel med symmetrisk hemlighet:

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

Samma hemlighet används för att signera och verifiera, så verifieraren måste inneha nyckeln som utfärdaren använde. För tjänster där kameran är utfärdaren (som delar ut tokens till en parad telefon), behåll hemligheten på kamerans filsystem och behandla den som vilken annan långlivad inloggningsuppgift som helst – se Drift: nycklar, utgång och felsökning.

Anteckning

Denna modul förlitar sig på hmac och hashlib, vilka båda är inbyggda i kameran. Ingen extern konfiguration behövs. Nycklar kan ha vilken längd som helst, men HMAC-konstruktionen är mest användbar med nycklar som är minst lika långa som SHA-256:s blockstorlek (32 byte).

jwt — JSON Web Tokens¶

Funktioner¶

Undantag¶

Exempel¶

`jwt` — JSON Web Tokens¶