Cheatsheet¶

This cheatsheet provides quick reference for the joserfc library, covering key management (JWK), signing (JWS), encryption (JWE), and tokens (JWT).

Installation¶

pip install joserfc

JWK (JSON Web Key)¶

Manage cryptographic keys.

Import Keys¶

Import keys from various sources with jwk.import_key() method:

from joserfc import jwk

# Import generic JWK (dict) - auto-detects type
key = jwk.import_key({
    "kty": "oct",
    "k": "eW91ci1zZWNyZXQta2V5", # "your-secret-key" base64url encoded
    "use": "sig"
})

# Import Symmetric Key (Oct) from string/bytes
oct_key = jwk.import_key("your-secret-key", "oct")

# Import RSA Key from PEM
pem_rsa = """-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlwwS7I3t2fSTawG1DcNF
Cu6NECHT3eVkr2lYXXD2hz4ILiIST2Q3/YpzNA9CrRZDseA24Ax/8UNZsMi8G1M8
Dpq1jUMKA4NrWOTrraZQmD9q4+rZLNx7M5NV8uojSoPWFYIBFwXgwzJYOZ8RVobJ
aDx6GWhWherJ1/xWrQS817mt0MwrDB9fm9RvfpBYqAKgfll6oL7MDuDTAY39yvi/
UkZGwD9b8ItdnssaiGBzqVG2inO1rUIAJ5WMK1P6K1MiSXdHRhgdSeDqMq07hFP3
IQWaOT6EWPOAEDS6E3eaHDkqNZTIrVmsVW2ScmttjRSXrmrk2U10ihiF79L9KKS/
nwIDAQAB
-----END PUBLIC KEY-----"""
rsa_key = jwk.import_key(pem_rsa, "RSA")

# Import EC Key from PEM
pem_ec = """-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBdy4ZhgfXuBXLWgIAVfH+qqbZ4ne
opI4cgNaZ85tQM0rzghtBbXTnP9gxj49fhos3P34nBlIdShM9vaS0yQwcA==
-----END PUBLIC KEY-----"""
ec_key = jwk.import_key(pem_rsa, "EC")

# Import OKP (Ed25519/X25519) from PEM
pem_okp = """-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAqfwZCPkk+0u/GeXg10A3xt6JdNgqcLHqL3jKgBmL8Ow=
-----END PUBLIC KEY-----"""
okp_key = jwk.import_key(pem_okp, "OKP")

Import keys directly using the key type class:

from joserfc.jwk import OctKey, RSAKey, ECKey, OKPKey

oct_key = OctKey.import_key("your-secret-key")

# Import RSA Key from PEM
rsa_key = RSAKey.import_key(pem_rsa)

# Import EC Key from PEM
ec_key = ECKey.import_key(pem_ec)

# Import OKP (Ed25519/X25519) from PEM
okp_key = OKPKey.import_key(pem_okp)

Generate Keys¶

from joserfc.jwk import KeyParameters
from joserfc.jwk import OctKey, RSAKey, ECKey, OKPKey

# Generate Oct (Symmetric) Key - size in bits
key = OctKey.generate_key(256) # 256 bits = 32 bytes

# Generate RSA Key
params: KeyParameters = {"use": "sig"}
rsa = RSAKey.generate_key(2048)

# Generate EC Key (P-256, P-384, P-521, secp256k1)
ec = ECKey.generate_key("P-256")

# Generate OKP Key (Ed25519, Ed448, X25519, X448)
okp = OKPKey.generate_key("Ed25519")

Use KeyParameters¶

When importing a key, or generating a key, you can pass a KeyParameters to set additional key properties.

from joserfc.jwk import KeyParameters
from joserfc.jwk import OctKey, RSAKey

params: KeyParameters = {"use": "sig"}

oct_key = OctKey.import_key("your-secret-key", params)
rsa_key = RSAKey.generate_key(2048, params)

Export Keys¶

# To Dict (for JSON)
public_jwk = key.as_dict(private=False)
private_jwk = key.as_dict(private=True)

# To PEM (Asymmetric keys only)
pem_bytes = key.as_pem(private=True)

Key Sets (JWKS)¶

from joserfc.jwk import KeySet
import json

# Import from file
with open("jwks.json") as f:
    key_set = KeySet.import_key_set(json.load(f))

# Import from URL
# resp = requests.get("https://example.com/.well-known/jwks.json")
# key_set = KeySet.import_key_set(resp.json())

# Generate Key Set
key_set = KeySet.generate_key_set("EC", "P-256", count=4)

JWS (JSON Web Signature)¶

Sign and verify data.

Compact Serialization (Most Common)¶

from joserfc import jws
from joserfc.jwk import OctKey

key = OctKey.import_key("<your-secret-key>")
payload = "hello world"

# Sign
protected = {"alg": "HS256"}
token = jws.serialize_compact(protected, payload, key)
# 'eyJ...'

# Verify
obj = jws.deserialize_compact(token, key)
print(obj.payload) # b'hello world'
print(obj.protected) # {'alg': 'HS256'}

JSON Serialization (Multiple Signatures)¶

from joserfc import jws
from joserfc.jwk import RSAKey, ECKey, KeySet

rsa_key = RSAKey.generate_key(2048)
ec_key = ECKey.generate_key("P-256")

# Create KeySet with both keys
private_key_set = KeySet([rsa_key, ec_key])

# Usually you would export the public keys and provide them to public
# through a URL such as https://example.com/jwks.json
public_jwks = private_key_set.as_dict(private=False)

payload = b"secure message"

# Sign with multiple keys
members = [
    {"protected": {"alg": "RS256"}, "header": {"kid": rsa_key.kid}},
    {"protected": {"alg": "ES256"}, "header": {"kid": ec_key.kid}}
]

# Use KeySet for private keys if multiple
value = jws.serialize_json(members, payload, private_key_set)

# Verify usually happens on the client side, clients can fetch the public keys from a URL
public_key_set = KeySet.import_key_set(public_jwks)
obj = jws.deserialize_json(value, public_key_set)
print(obj.payload) # b'secure message'

JWE (JSON Web Encryption)¶

Encrypt and decrypt data.

Compact Encryption¶

from joserfc import jwe
from joserfc.jwk import OctKey

# Shared secret key (must match algorithm requirements)
key = OctKey.generate_key(128) # 128 bits for A128KW

protected = {"alg": "A128KW", "enc": "A128GCM"}
plaintext = "secret message"

# Encrypt
jwe_token = jwe.encrypt_compact(protected, plaintext, key)

# Decrypt
obj = jwe.decrypt_compact(jwe_token, key)
print(obj.plaintext) # b'secret message'

JSON Encryption (Multiple Recipients)¶

from joserfc import jwe
from joserfc.jwk import OctKey, RSAKey, KeySet

# General JSON Encryption builder
enc_obj = jwe.GeneralJSONEncryption({"enc": "A128GCM"}, b"payload")

# Add recipient 1
key1 = OctKey.generate_key(128)
key1.ensure_kid()
enc_obj.add_recipient({"alg": "A128KW", "kid": key1.kid})

# Add recipient 2
key2 = RSAKey.generate_key(2048)

# You use public key to encrypt and private key to decrypt
public_key = RSAKey.import_key(key2.public_key)
public_key.ensure_kid()
enc_obj.add_recipient({"alg": "RSA-OAEP", "kid": public_key.kid})

# Encrypt, we use public keys for recipients
data = jwe.encrypt_json(enc_obj, KeySet([key1, public_key]))

# Decrypt, we use private keys for decryption
obj = jwe.decrypt_json(data, KeySet([key1, key2]))
print(obj.plaintext) # b'payload'

JWT (JSON Web Token)¶

Create and verify tokens with claims.

Encode (Create Token)¶

from joserfc import jwt
from joserfc.jwk import OctKey
import datetime

key = OctKey.import_key("secret")
header = {"alg": "HS256"}
claims = {
    "iss": "https://myapp.com",
    "sub": "user123",
    "exp": datetime.datetime.now(datetime.UTC) + datetime.timedelta(hours=1)
}

token = jwt.encode(header, claims, key)

Decode (Verify Token)¶

# Verify and decode
# Note: decode verifies signature automatically
obj = jwt.decode(token, key)
print(obj.claims)
# {'iss': '...', 'sub': '...', 'exp': ...}

Validate Claims¶

Use JWTClaimsRegistry to enforce claim rules (essential, values, format).

from joserfc.jwt import JWTClaimsRegistry
from joserfc.errors import ClaimError

# Define requirements
registry = JWTClaimsRegistry(
    iss={"essential": True, "value": "https://myapp.com"},
    aud={"essential": True, "values": ["my-api", "other-api"]},
    role={"value": "admin"} # Custom claim check
)

token_obj = jwt.decode(token, key)

try:
    registry.validate(token_obj.claims)
    print("Claims valid")
except ClaimError as e:
    print(f"Validation failed: {e}")

Nested JWT (JWE containing JWT)¶

To create an encrypted JWT, use JWERegistry.

from joserfc import jwt, jwe
from joserfc.jwk import OctKey

key = OctKey.generate_key(128)
header = {"alg": "A128KW", "enc": "A128GCM"}
claims = {"secret": "data"}

# Pass JWERegistry to indicate JWE mode
registry = jwe.JWERegistry()
token = jwt.encode(header, claims, key, registry=registry)