`jwt` — JSON Web Tokens¶

Невелика реалізація стандарту JSON Web Token (JWT) для MicroPython. JWT — це компактний, URL-безпечний контейнер для JSON-навантаження, який видавець підписує, щоб верифікатор міг виявити підробку та закінчення терміну дії.

Цей порт MicroPython навмисно мінімальний:

Підтримується лише HS256 (HMAC з SHA-256). Алгоритми RSA / ECDSA / EdDSA не реалізовані; видавець та верифікатор мають спільний симетричний секретний ключ.
Необов’язкова заявка exp (закінчення терміну дії) враховується. Інші зареєстровані заявки (nbf, iat, iss, aud, sub, jti) передаються без змін у навантаженні, але не перевіряються; застосунок перевіряє їх за потреби.
Без обробки ротації ключів, JWKS або списку аудиторій.

Функції¶

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

Кодувати payload у підписаний JWT та повернути отриману компактну серіалізацію (рядок str форми "header.payload.signature", кожен сегмент закодований у Base64-URL).

payload: Словник заявок, серіалізовуваний у JSON. Стандартні заявки (exp, iat, sub, …) передаються дослівно; дозволені власні ключі застосунку.
key: Спільний секрет HMAC. Переважно bytes; str автоматично кодується у UTF-8.
algorithm: Має бути "HS256" (за замовчуванням). Будь-яке інше значення викидає exceptions.InvalidAlgorithmError.

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

Перевірити підпис token та (за наявності) його заявку exp, і повернути декодований словник навантаження. При будь-якій невдачі викидається підклас exceptions.PyJWTError — зазвичай викликач перехоплює базовий клас.

token: Компактний рядок JWT, створений encode() (або будь-яким сумісним видавцем).
key: Спільний секрет HMAC. Має збігатися з ключем, використаним під час кодування.
algorithms: Список алгоритмів, які викликач готовий прийняти. HS256 має бути присутнім, а заголовок токена alg має бути у списку. За замовчуванням ["HS256"].

Викидає:

exceptions.InvalidAlgorithmError — HS256 відсутній у algorithms, або заголовок токена alg є чимось іншим, ніж HS256.
exceptions.InvalidTokenError — токен має неправильну структуру (не розбивається на три сегменти Base64-URL, або сегмент не вдається декодувати / розібрати як JSON).
exceptions.InvalidSignatureError — підпис не відповідає перерахованому HMAC по заголовку та навантаженню.
exceptions.ExpiredSignatureError — навантаження містить заявку exp, значення якої менше поточного часу Unix. Годинник камери має бути встановлений для того, щоб ця перевірка мала сенс; дивіться ntptime.settime().

Винятки¶

Усі винятки вкладені під атрибут модуля jwt.exceptions.

exception exceptions.PyJWTError¶: Базовий клас для будь-якого збою JWT. Перехоплюйте його, якщо не потрібно розрізняти наведені нижче випадки.

exception exceptions.InvalidTokenError¶: Токен структурно недійсний — неправильна кількість сегментів, сегмент, що не вдається декодувати з Base64, або JSON, що не вдається розібрати. Підклас exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError¶: Алгоритм токена відсутній у прийнятному списку викликача, або викликач запитав алгоритм, відмінний від HS256. Підклас exceptions.PyJWTError.

exception exceptions.InvalidSignatureError¶: Підпис токена не відповідає HMAC, обчисленому з заголовка та навантаження за допомогою наданого ключа. Підклас exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError¶: Заявка exp токена знаходиться у минулому. Підклас exceptions.PyJWTError. Системний час камери має бути встановлений (через ntptime.settime()), щоб ця перевірка мала сенс.

Приклад¶

Цикл видачі/перевірки з симетричним секретом:

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

Той самий секрет використовується для підписання та перевірки, тому верифікатор повинен мати ключ, який використовував видавець. Для сервісів, де камера є видавцем (роздає токени парному телефону), зберігайте секрет у файловій системі камери та поводьтеся з ним, як з будь-якими іншими довгостроковими обліковими даними — дивіться Операції: ключі, термін дії та усунення несправностей.

Примітка

Цей модуль покладається на hmac та hashlib, обидва з яких вбудовані у камеру. Зовнішнє налаштування не потрібне. Ключі можуть бути будь-якої довжини, але конструкція HMAC найбільш корисна з ключами, довжина яких щонайменше дорівнює розміру блоку SHA-256 (32 байти).

jwt — JSON Web Tokens¶

Функції¶

Винятки¶

Приклад¶

`jwt` — JSON Web Tokens¶