jwt — JSON Web Tokens

Pieni toteutus JSON Web Token (JWT) -standardista MicroPythonille. JWT on tiivis, URL-turvallinen säiliö JSON-hyötykuormalle, jonka myöntäjä allekirjoittaa, jotta vahvistaja voi havaita peukaloinnin ja vanhentumisen.

Tämä MicroPython-portti on tarkoituksella hyvin pieni:

• Vain HS256 (HMAC SHA-256:lla) on tuettu. RSA / ECDSA / EdDSA -algoritmeja ei ole toteutettu; myöntäjän ja vahvistajan on jaettava symmetrinen salainen avain.

• Valinnainen exp-vaatimus (vanhentuminen) huomioidaan. Muut rekisteröidyt vaatimukset (nbf, iat, iss, aud, sub, jti) välitetään muuttumattomina hyötykuormassa mutta niitä ei validoida; sovellus tarkistaa ne jos se tarvitsee.

• Ei avainten kiertoa, JWKS:ää tai kohdeyleisölistan käsittelyä.

Funktiot

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

Koodaa payload allekirjoitetuksi JWT:ksi ja palauttaa tuloksena saadun tiiviin serialisoinnin (str, joka on muotoa "header.payload.signature", kunkin segmentin ollessa Base64-URL-koodattu).

payload

JSON-serialisoitava sanakirja vaatimuksista. Standardivaatimukset (exp, iat, sub, …) välitetään sellaisinaan; mukautetut sovellusavaimet ovat sallittuja.

key

Jaettu HMAC-salaisuus. bytes on suositeltava; str UTF-8-koodataan automaattisesti.

algorithm

Täytyy olla "HS256" (oletus). Mikä tahansa muu nostaa exceptions.InvalidAlgorithmError-poikkeuksen.

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

Vahvistaa token-tunnisteen allekirjoituksen ja (jos läsnä) sen exp-vaatimuksen, ja palauttaa dekoodatun hyötykuormasanakirjan. Nostaa exceptions.PyJWTError-poikkeuksen aliluokan minkä tahansa epäonnistumisen tapauksessa – kutsuja yleensä nappaa kantaluokan.

token

encode()-funktion (tai minkä tahansa yhteensopivan myöntäjän) tuottama tiivis JWT-merkkijono.

key

Jaettu HMAC-salaisuus. Täytyy vastata koodaushetkellä käytettyä avainta.

algorithms

Lista algoritmeista, jotka kutsuja on valmis hyväksymään. HS256 täytyy olla läsnä, ja tunnisteen otsakkeen alg täytyy olla listassa. Oletuksena ["HS256"].

Nostaa:

• exceptions.InvalidAlgorithmError – HS256 ei ole algorithms-listassa, tai tunnisteen otsakkeen alg on jotain muuta kuin HS256.

• exceptions.InvalidTokenError – tunniste on virheellisesti muodostettu (ei jakaudu kolmeen Base64-URL-segmenttiin, tai segmentin dekoodaus / jäsentäminen JSON:ksi epäonnistuu).

• exceptions.InvalidSignatureError – allekirjoitus ei vastaa otsakkeesta ja hyötykuormasta uudelleen laskettua HMAC-arvoa.

• exceptions.ExpiredSignatureError – hyötykuorma sisältää exp-vaatimuksen, jonka arvo on pienempi kuin nykyinen Unix-aika. Kameran kello täytyy olla asetettu, jotta tämä tarkistus on merkityksellinen; katso ntptime.settime().

Poikkeukset

Kaikki poikkeukset on sijoitettu moduulin attribuutin jwt.exceptions alle.

exception exceptions.PyJWTError

Jokaisen JWT-epäonnistumisen kantaluokka. Nappaa tämä, jos sinun ei tarvitse erottaa alla olevia tapauksia toisistaan.

exception exceptions.InvalidTokenError

Tunniste on rakenteellisesti virheellinen – väärä määrä segmenttejä, segmentti jonka Base64-dekoodaus epäonnistuu, tai JSON jonka jäsentäminen epäonnistuu. exceptions.PyJWTError-poikkeuksen aliluokka.

exception exceptions.InvalidAlgorithmError

Tunnisteen algoritmi ei ole kutsujan hyväksymässä listassa, tai kutsuja pyysi muuta algoritmia kuin HS256. exceptions.PyJWTError-poikkeuksen aliluokka.

exception exceptions.InvalidSignatureError

Tunnisteen allekirjoitus ei vastaa otsakkeesta ja hyötykuormasta annetulla avaimella laskettua HMAC-arvoa. exceptions.PyJWTError-poikkeuksen aliluokka.

exception exceptions.ExpiredSignatureError

Tunnisteen exp-vaatimus on menneisyydessä. exceptions.PyJWTError-poikkeuksen aliluokka. Kameran reaaliaikakellon aika täytyy olla asetettu (kautta ntptime.settime()), jotta tämä tarkistus on merkityksellinen.

Esimerkki

Symmetrisen salaisuuden myöntö-/vahvistussykli:

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

Samaa salaisuutta käytetään allekirjoittamiseen ja vahvistamiseen, joten vahvistajan on pidettävä hallussaan se avain, jota myöntäjä käytti. Palveluissa, joissa kamera on myöntäjä (jakaen tunnisteita pariutetulle puhelimelle), pidä salaisuus kameran tiedostojärjestelmässä ja käsittele sitä kuten mitä tahansa muuta pitkäikäistä tunnistetietoa – katso Käyttö: avaimet, vanheneminen ja vianmääritys.

Muista

Tämä moduuli nojaa hmac- ja hashlib-moduuleihin, jotka molemmat ovat sisäänrakennettuja kameraan. Ulkoista konfigurointia ei tarvita. Avaimet voivat olla minkä tahansa pituisia, mutta HMAC-rakenne on hyödyllisin avaimilla, jotka ovat vähintään yhtä pitkiä kuin SHA-256:n lohkokoko (32 tavua).