`jwt` — JSON Web Token¶

MicroPython용 JSON Web Token(JWT) 표준의 소규모 구현입니다. JWT는 발급자가 서명하여 검증자가 변조와 만료를 감지할 수 있게 하는 JSON 페이로드를 위한 간결하고 URL에 안전한 컨테이너입니다.

이 MicroPython 포트는 의도적으로 매우 작습니다:

HS256(SHA-256을 사용하는 HMAC)만 지원됩니다. RSA / ECDSA / EdDSA 알고리즘은 구현되어 있지 않으며, 발급자와 검증자는 대칭 비밀 키를 공유해야 합니다.
선택적인 exp(만료) 클레임은 준수됩니다. 다른 등록된 클레임(nbf, iat, iss, aud, sub, jti)은 페이로드에서 변경 없이 그대로 전달되지만 검증되지 않습니다. 애플리케이션이 필요하다면 직접 확인합니다.
키 회전, JWKS 또는 대상(audience) 목록 처리는 없습니다.

함수¶

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

payload를 서명된 JWT로 인코딩하고 결과 간결 직렬화("header.payload.signature" 형태의 str로, 각 세그먼트는 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: encode()(또는 호환되는 발급자)가 생성한 압축된 JWT 문자열입니다.
key: 공유 HMAC 비밀입니다. 인코딩 시 사용한 키와 일치해야 합니다.
algorithms: 호출자가 받아들일 의향이 있는 알고리즘 목록입니다. HS256이 존재해야 하며, 토큰 헤더의 alg가 목록 안에 있어야 합니다. 기본값은 ["HS256"]입니다.

발생 예외:

exceptions.InvalidAlgorithmError – HS256이 algorithms에 없거나, 토큰 헤더의 alg가 HS256 이외의 값인 경우.
exceptions.InvalidTokenError – 토큰이 잘못 형성된 경우(세 개의 Base64-URL 세그먼트로 분리되지 않거나, 세그먼트가 JSON으로 디코딩/파싱되지 못하는 경우).
exceptions.InvalidSignatureError – 서명이 헤더와 페이로드에 대해 다시 계산한 HMAC와 일치하지 않는 경우.
exceptions.ExpiredSignatureError – 페이로드에 값이 현재 Unix 시간보다 작은 exp 클레임이 포함된 경우. 이 검사가 의미를 가지려면 카메라의 시계가 설정되어 있어야 합니다. 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 Token¶

함수¶

예외¶

예제¶

`jwt` — JSON Web Token¶