`jwt` — JSON Web Tokens#

Niewielka implementacja standardu JSON Web Token (JWT) dla MicroPython. JWT to kompaktowy, bezpieczny dla adresów URL kontener na ładunek JSON, który wystawca podpisuje, aby weryfikator mógł wykryć manipulację i wygaśnięcie.

Ten port MicroPython jest celowo bardzo mały:

Obsługiwany jest tylko HS256 (HMAC z SHA-256). Algorytmy RSA / ECDSA / EdDSA nie są zaimplementowane; wystawca i weryfikator muszą współdzielić symetryczny klucz tajny.
Opcjonalne roszczenie exp (wygaśnięcie) jest respektowane. Inne zarejestrowane roszczenia (nbf, iat, iss, aud, sub, jti) są przekazywane w ładunku bez zmian, ale nie są walidowane; aplikacja sprawdza je, jeśli mają dla niej znaczenie.
Brak obsługi rotacji kluczy, JWKS ani list odbiorców.

Funkcje#

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

Koduje payload do podpisanego JWT i zwraca powstałą kompaktową serializację (str w postaci "header.payload.signature", gdzie każdy segment jest zakodowany w Base64-URL).

payload: Słownik roszczeń możliwy do serializacji w formacie JSON. Standardowe roszczenia (exp, iat, sub, …) są przekazywane dosłownie; niestandardowe klucze aplikacji są dozwolone.
key: Współdzielony sekret HMAC. Preferowany jest bytes; str jest automatycznie kodowany w UTF-8.
algorithm: Musi być "HS256" (wartość domyślna). Cokolwiek innego zgłasza exceptions.InvalidAlgorithmError.

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

Weryfikuje podpis token oraz (jeśli jest obecne) jego roszczenie exp i zwraca zdekodowany słownik ładunku. Zgłasza podklasę exceptions.PyJWTError w przypadku jakiegokolwiek niepowodzenia – wywołujący zwykle przechwytuje klasę bazową.

token: Kompaktowy łańcuch JWT wytworzony przez encode() (lub dowolnego kompatybilnego wystawcę).
key: Współdzielony sekret HMAC. Musi pasować do klucza użytego podczas kodowania.
algorithms: Lista algorytmów, które wywołujący jest gotów zaakceptować. Musi być na niej obecny HS256, a nagłówek alg tokenu musi znajdować się na tej liście. Domyślnie ["HS256"].

Zgłasza:

exceptions.InvalidAlgorithmError – HS256 nie znajduje się na liście algorithms lub nagłówek alg tokenu jest czymś innym niż HS256.
exceptions.InvalidTokenError – token jest źle sformułowany (nie dzieli się na trzy segmenty Base64-URL lub segment nie daje się zdekodować / sparsować jako JSON).
exceptions.InvalidSignatureError – podpis nie pasuje do ponownie obliczonego HMAC dla nagłówka i ładunku.
exceptions.ExpiredSignatureError – ładunek zawiera roszczenie exp, którego wartość jest mniejsza niż bieżący czas uniksowy. Aby to sprawdzenie miało sens, zegar kamery musi być ustawiony; zobacz ntptime.settime().

Wyjątki#

Wszystkie wyjątki są zagnieżdżone w atrybucie modułu jwt.exceptions.

exception exceptions.PyJWTError#: Klasa bazowa dla każdego niepowodzenia JWT. Przechwyć ją, jeśli nie musisz rozróżniać między poniższymi przypadkami.

exception exceptions.InvalidTokenError#: Token jest strukturalnie nieprawidłowy – niewłaściwa liczba segmentów, segment, którego nie udaje się zdekodować z Base64, lub JSON, którego nie udaje się sparsować. Podklasa exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError#: Algorytm tokenu nie znajduje się na liście akceptowanej przez wywołującego lub wywołujący zażądał algorytmu innego niż HS256. Podklasa exceptions.PyJWTError.

exception exceptions.InvalidSignatureError#: Podpis tokenu nie pasuje do HMAC obliczonego z nagłówka i ładunku przy użyciu podanego klucza. Podklasa exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError#: Roszczenie exp tokenu odnosi się do przeszłości. Podklasa exceptions.PyJWTError. Aby to sprawdzenie miało sens, czas zegarowy kamery musi być ustawiony (za pomocą ntptime.settime()).

Przykład#

Cykl wystawiania/weryfikacji z sekretem symetrycznym:

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

Ten sam sekret jest używany do podpisywania i weryfikacji, więc weryfikator musi posiadać klucz, którego użył wystawca. W przypadku usług, w których kamera jest wystawcą (wydając tokeny sparowanemu telefonowi), przechowuj sekret w systemie plików kamery i traktuj go jak każde inne długotrwałe poświadczenie – zobacz Operacje: klucze, wygasanie i rozwiązywanie problemów.

Informacja

Ten moduł opiera się na hmac i hashlib, które są wbudowane w kamerę. Żadna zewnętrzna konfiguracja nie jest potrzebna. Klucze mogą mieć dowolną długość, ale konstrukcja HMAC jest najbardziej użyteczna z kluczami co najmniej tak długimi jak rozmiar bloku SHA-256 (32 bajty).

jwt — JSON Web Tokens#

Funkcje#

Wyjątki#

Przykład#

`jwt` — JSON Web Tokens#