`jwt` --- JSON Web Tokens¶

Một triển khai nhỏ gọn của tiêu chuẩn JSON Web Token (JWT) cho MicroPython. JWT là một container nhỏ gọn, an toàn URL cho payload JSON mà người phát hành ký để người xác minh có thể phát hiện sự giả mạo và hết hạn.

Cổng MicroPython này được thiết kế nhỏ gọn có chủ ý:

Chỉ hỗ trợ HS256 (HMAC với SHA-256). Các thuật toán RSA / ECDSA / EdDSA không được triển khai; người phát hành và người xác minh phải chia sẻ một khóa bí mật đối xứng.
Claim exp (hết hạn) tùy chọn được xử lý. Các claim đã đăng ký khác (nbf, iat, iss, aud, sub, jti) được chuyển qua không thay đổi trong payload nhưng không được xác thực; ứng dụng kiểm tra chúng nếu cần.
Không có xử lý xoay khóa, JWKS, hoặc danh sách đối tượng nhận.

Các hàm¶

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

Mã hóa payload thành JWT đã ký và trả về chuỗi serialization gọn (một str có dạng "header.payload.signature", mỗi phân đoạn được mã hóa Base64-URL).

payload: Một dict của các claim có thể tuần tự hóa JSON. Các claim chuẩn (exp, iat, sub, ...) được chuyển qua nguyên vẹn; các khóa ứng dụng tùy chỉnh được phép.
key: Bí mật HMAC được chia sẻ. bytes được ưu tiên; str được mã hóa UTF-8 tự động.
algorithm: Phải là "HS256" (mặc định). Bất kỳ giá trị nào khác sẽ đưa ra exceptions.InvalidAlgorithmError.

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

Xác minh chữ ký của token và (nếu có) claim exp của nó, và trả về dict payload đã giải mã. Đưa ra một lớp con của exceptions.PyJWTError khi có bất kỳ lỗi nào -- người gọi thường bắt lớp cơ sở.

token: Chuỗi JWT gọn được tạo bởi encode() (hoặc bất kỳ người phát hành tương thích nào).
key: Bí mật HMAC được chia sẻ. Phải khớp với khóa được sử dụng lúc mã hóa.
algorithms: Danh sách các thuật toán mà người gọi sẵn sàng chấp nhận. HS256 phải có mặt, và alg trong header của token phải có trong danh sách. Mặc định là ["HS256"].

Đưa ra:

exceptions.InvalidAlgorithmError -- HS256 không có trong algorithms, hoặc alg trong header của token là bất kỳ giá trị nào khác ngoài HS256.
exceptions.InvalidTokenError -- token bị lỗi định dạng (không phân tách thành ba phân đoạn Base64-URL, hoặc một phân đoạn không thể giải mã / phân tích cú pháp dưới dạng JSON).
exceptions.InvalidSignatureError -- chữ ký không khớp với HMAC được tính lại từ header và payload.
exceptions.ExpiredSignatureError -- payload chứa claim exp có giá trị nhỏ hơn thời gian Unix hiện tại. Đồng hồ của camera phải được đặt để kiểm tra này có ý nghĩa; xem ntptime.settime().

Các ngoại lệ¶

Tất cả các ngoại lệ được lồng dưới thuộc tính mô-đun jwt.exceptions.

exception exceptions.PyJWTError¶: Lớp cơ sở cho mọi lỗi JWT. Bắt lớp này nếu bạn không cần phân biệt giữa các trường hợp bên dưới.

exception exceptions.InvalidTokenError¶: Token không hợp lệ về mặt cấu trúc -- sai số phân đoạn, phân đoạn không thể giải mã Base64, hoặc JSON không thể phân tích cú pháp. Lớp con của exceptions.PyJWTError.

exception exceptions.InvalidAlgorithmError¶: Thuật toán của token không có trong danh sách được người gọi chấp nhận, hoặc người gọi yêu cầu thuật toán khác ngoài HS256. Lớp con của exceptions.PyJWTError.

exception exceptions.InvalidSignatureError¶: Chữ ký của token không khớp với HMAC được tính từ header và payload bằng khóa được cung cấp. Lớp con của exceptions.PyJWTError.

exception exceptions.ExpiredSignatureError¶: Claim exp của token đã quá hạn. Lớp con của exceptions.PyJWTError.. Thời gian thực của camera phải được đặt (qua ntptime.settime()) để kiểm tra này có ý nghĩa.

Ví dụ¶

Chu trình phát hành/xác minh với bí mật đối xứng:

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

Cùng một bí mật được sử dụng để ký và xác minh, vì vậy người xác minh phải giữ khóa mà người phát hành đã dùng. Đối với các dịch vụ mà camera là người phát hành (cấp token cho điện thoại được ghép nối), hãy giữ bí mật trên hệ thống tệp camera và xử lý nó như bất kỳ thông tin xác thực dài hạn nào khác -- xem Các thao tác: khóa, hết hạn và xử lý sự cố.

Ghi chú

Mô-đun này dựa trên hmac và hashlib, cả hai đều được tích hợp vào camera. Không cần cấu hình bên ngoài. Khóa có thể có độ dài bất kỳ, nhưng cấu trúc HMAC hữu ích nhất với các khóa ít nhất bằng kích thước khối SHA-256 (32 byte).

jwt --- JSON Web Tokens¶

Các hàm¶

Các ngoại lệ¶

Ví dụ¶

`jwt` --- JSON Web Tokens¶