jam.jose.jwk¶

jwk ¶

Classes:

Name	Description
`JWK`	JSON Web Key - RFC 7517.
`JWKCommon`	Common JWK parameters shared across all key types - RFC 7517 Section 4.
`JWKEC`	Elliptic Curve Key - RFC 7517 Section 6.2.
`JWKOct`	Symmetric (Octet Sequence) Key - RFC 7517 Section 6.4.
`JWKRSA`	RSA Key - RFC 7517 Section 6.3.
`JWKSet`	JWK Set - RFC 7517 Section 5.

Attributes:

Name	Type	Description
`JWKDict`		Union type representing any valid JWK dict.

JWKDict `module-attribute` ¶

JWKDict = JWKRSA | JWKEC | JWKOct

Union type representing any valid JWK dict.

JWK ¶

JWK(data: dict[str, Any])

Bases: BaseJWK

JSON Web Key - RFC 7517.

Provides JWK validation and signing capabilities.

Example

>>> jwk = JWK.from_dict({"kty": "oct", "k": "your-secret-key"})
>>> jwk.sign(b"data", "HS256")
>>> jwk.verify(token)

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	Validated JWK dict.	required

Methods:

Name	Description
`from_dict`	Create JWK from dict.
`sign`	Sign data using JWK.
`to_dict`	Convert JWK to dict.
`validate`	Validate and normalize JWK dict.
`verify`	Verify JWS token and return payload.

Attributes:

Name	Type	Description
`alg`	`str \| None`	Get algorithm from JWK if set.
`kid`	`str \| None`	Get key ID if set.
`kty`	`str`	Get key type.

alg `property` ¶

alg: str | None

Get algorithm from JWK if set.

Returns:

Type	Description
`str \| None`	Algorithm or None.

kid `property` ¶

kid: str | None

Get key ID if set.

Returns:

Type	Description
`str \| None`	Key ID or None.

kty `property` ¶

kty: str

Get key type.

Returns:

Type	Description
`str`	Key type (RSA, EC, oct).

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> JWK

Create JWK from dict.

Alias for JWK.validate().

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	JWK dict.	required

Returns:

Type	Description
`JWK`	JWK instance.

sign ¶

sign(data: bytes, alg: str | None = None) -> str

Sign data using JWK.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	Data to sign.	required
`alg`	`str \| None`	Algorithm to use. If None, uses default for kty.	`None`

Returns:

Type	Description
`str`	JWS compact serialization string.

Raises:

Type	Description
`ValueError`	If algorithm is not supported or key is invalid.

to_dict ¶

to_dict() -> dict[str, Any]

Convert JWK to dict.

Returns:

Type	Description
`dict[str, Any]`	JWK dict.

validate `staticmethod` ¶

validate(data: dict[str, Any]) -> JWK

Validate and normalize JWK dict.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	JWK dict to validate.	required

Returns:

Type	Description
`JWK`	JWK instance.

Raises:

Type	Description
`JamJWKValidationError`	If JWK is invalid.

verify ¶

verify(
    token: str, alg: str | None = None
) -> dict[str, Any]

Verify JWS token and return payload.

Parameters:

Name	Type	Description	Default
`token`	`str`	JWS compact serialization token.	required
`alg`	`str \| None`	Algorithm to use. If None, uses default for kty.	`None`

Returns:

Type	Description
`dict[str, Any]`	dict with 'header' and 'payload' keys.

Raises:

Type	Description
`ValueError`	If signature is invalid.

JWKCommon ¶

Bases: TypedDict

Common JWK parameters shared across all key types - RFC 7517 Section 4.

Attributes:

Name	Type	Description
`alg`	`str`	Algorithm. Identifies the algorithm intended for use with the key.
`key_ops`	`list[str]`	Key Operations. Identifies the operations for which the key is intended.
`kid`	`str`	Key ID. Unique identifier for the key.
`kty`	`str`	Key Type. Required. Identifies the cryptographic algorithm family.
`use`	`Literal['sig', 'enc']`	Public Key Use. Identifies the intended use of the public key.
`x5c`	`str`	X.509 Certificate Chain. Base64-encoded X.509 public key certificate chain.
`x5t`	`str`	X.509 Certificate Thumbprint. Base64-encoded SHA-1 thumbprint of the certificate.
`x5t_S256`	`str`	X.509 Certificate SHA-256 Thumbprint. Base64-encoded SHA-256 thumbprint.
`x5u`	`str`	X.509 URL. URI pointing to an X.509 public key certificate or chain.

alg `instance-attribute` ¶

alg: str

Algorithm. Identifies the algorithm intended for use with the key.

key_ops `instance-attribute` ¶

key_ops: list[str]

Key Operations. Identifies the operations for which the key is intended.

kid `instance-attribute` ¶

kid: str

Key ID. Unique identifier for the key.

kty `instance-attribute` ¶

kty: str

Key Type. Required. Identifies the cryptographic algorithm family.

use `instance-attribute` ¶

use: Literal['sig', 'enc']

Public Key Use. Identifies the intended use of the public key.

x5c `instance-attribute` ¶

x5c: str

X.509 Certificate Chain. Base64-encoded X.509 public key certificate chain.

x5t `instance-attribute` ¶

x5t: str

X.509 Certificate Thumbprint. Base64-encoded SHA-1 thumbprint of the certificate.

x5t_S256 `instance-attribute` ¶

x5t_S256: str

X.509 Certificate SHA-256 Thumbprint. Base64-encoded SHA-256 thumbprint.

x5u `instance-attribute` ¶

x5u: str

X.509 URL. URI pointing to an X.509 public key certificate or chain.

JWKEC ¶

Bases: JWKCommon

Elliptic Curve Key - RFC 7517 Section 6.2.

Represents an elliptic curve public or private key.

Example

ec_key: JWKEC = { ... "kty": "EC", ... "crv": "P-256", ... "x": "f83OJ3D2xF1Bg8v...", ... "y": "x_FEzRu9m36HLN_t...", ... }

Attributes:

Name	Type	Description
`crv`	`Literal['P-256', 'P-384', 'P-521']`	Elliptic curve name. The curve on which the key is based.
`d`	`str`	EC private key value. The private key value. Present only in private keys.
`kty`	`Literal['EC']`	Key Type. Fixed to "EC".
`x`	`str`	EC x coordinate. The x coordinate of the elliptic curve point.
`y`	`str`	EC y coordinate. The y coordinate of the elliptic curve point.

crv `instance-attribute` ¶

crv: Literal['P-256', 'P-384', 'P-521']

Elliptic curve name. The curve on which the key is based.

d `instance-attribute` ¶

d: str

EC private key value. The private key value. Present only in private keys.

kty `instance-attribute` ¶

kty: Literal['EC']

Key Type. Fixed to "EC".

x `instance-attribute` ¶

x: str

EC x coordinate. The x coordinate of the elliptic curve point.

y `instance-attribute` ¶

y: str

EC y coordinate. The y coordinate of the elliptic curve point.

JWKOct ¶

Bases: JWKCommon

Symmetric (Octet Sequence) Key - RFC 7517 Section 6.4.

Represents a symmetric (secret) key.

Example

oct_key: JWKOct = { ... "kty": "oct", ... "k": "AyM32w-xOvmxxkBq...", ... }

Attributes:

Name	Type	Description
`k`	`str`	Key value. The base64url-encoded symmetric key value.
`kty`	`Literal['oct']`	Key Type. Fixed to "oct".

k `instance-attribute` ¶

k: str

Key value. The base64url-encoded symmetric key value.

kty `instance-attribute` ¶

kty: Literal['oct']

Key Type. Fixed to "oct".

JWKRSA ¶

Bases: JWKCommon

RSA Key - RFC 7517 Section 6.3.

Represents an RSA public or private key.

Example

rsa_key: JWKRSA = { ... "kty": "RSA", ... "n": "0vx7agoebGcQSuu...", ... "e": "AQAB", ... }

Attributes:

Name	Type	Description
`d`	`str`	RSA private exponent d. Present only in private keys.
`dp`	`str`	First factor exponent. d mod (p-1). Present only in private keys.
`dq`	`str`	Second factor exponent. d mod (q-1). Present only in private keys.
`e`	`str`	RSA exponent e. The exponent value for the RSA public key.
`kty`	`Literal['RSA']`	Key Type. Fixed to "RSA".
`n`	`str`	RSA modulus n. The modulus value for the RSA public key.
`p`	`str`	First prime p. First prime factor of n. Present only in private keys.
`q`	`str`	Second prime q. Second prime factor of n. Present only in private keys.
`qi`	`str`	First CRT coefficient. q^(-1) mod p. Present only in private keys.

d `instance-attribute` ¶

d: str

RSA private exponent d. Present only in private keys.

dp `instance-attribute` ¶

dp: str

First factor exponent. d mod (p-1). Present only in private keys.

dq `instance-attribute` ¶

dq: str

Second factor exponent. d mod (q-1). Present only in private keys.

e `instance-attribute` ¶

e: str

RSA exponent e. The exponent value for the RSA public key.

kty `instance-attribute` ¶

kty: Literal['RSA']

Key Type. Fixed to "RSA".

n `instance-attribute` ¶

n: str

RSA modulus n. The modulus value for the RSA public key.

p `instance-attribute` ¶

p: str

First prime p. First prime factor of n. Present only in private keys.

q `instance-attribute` ¶

q: str

Second prime q. Second prime factor of n. Present only in private keys.

qi `instance-attribute` ¶

qi: str

First CRT coefficient. q^(-1) mod p. Present only in private keys.

JWKSet ¶

JWKSet(keys: list[dict[str, Any]] | None = None)

Bases: BaseJWKSet

JWK Set - RFC 7517 Section 5.

Represents a set of JWKs. Used to organize and filter collections of keys.

Example

>>> jwkset = JWKSet(keys=[rsa_key, ec_key])
>>> jwkset.get_by_kid("my-key-id")
>>> jwkset.filter(kty="RSA")

Parameters:

Name	Type	Description	Default
`keys`	`list[dict[str, Any]] \| None`	List of JWK dicts.	`None`

Methods:

Name	Description
`filter`	Filter JWKs by criteria.
`from_dict`	Create JWKSet from dict.
`get_by_kid`	Get JWK by key ID (kid).
`get_by_kty`	Get all JWKs by key type.
`to_dict`	Convert JWKSet to dict.

filter ¶

filter(**criteria: Any) -> list[dict[str, Any]]

Filter JWKs by criteria.

Parameters:

Name	Type	Description	Default
`**criteria`	`Any`	Filter criteria (kty, use, alg, key_ops, kid).	`{}`

Returns:

Type	Description
`list[dict[str, Any]]`	List of matching JWK dicts.

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> JWKSet

Create JWKSet from dict.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	Dict with "keys" key.	required

Returns:

Type	Description
`JWKSet`	JWKSet instance.

Raises:

Type	Description
`JamJWKValidationError`	If data is invalid.

get_by_kid ¶

get_by_kid(kid: str) -> dict[str, Any] | None

Get JWK by key ID (kid).

Parameters:

Name	Type	Description	Default
`kid`	`str`	Key ID to search for.	required

Returns:

Type	Description
`dict[str, Any] \| None`	JWK dict if found, None otherwise.

get_by_kty ¶

get_by_kty(kty: str) -> list[dict[str, Any]]

Get all JWKs by key type.

Parameters:

Name	Type	Description	Default
`kty`	`str`	Key type (RSA, EC, oct).	required

Returns:

Type	Description
`list[dict[str, Any]]`	List of matching JWK dicts.

to_dict ¶

to_dict() -> dict[str, Any]

Convert JWKSet to dict.

Returns:

Type	Description
`dict[str, Any]`	dict with "keys" key containing list of JWKs.

jam.jose.jwk¶

jwk ¶

JWKDict module-attribute ¶

JWK ¶

alg property ¶

kid property ¶

kty property ¶

from_dict classmethod ¶

sign ¶

to_dict ¶

validate staticmethod ¶

verify ¶

JWKCommon ¶

alg instance-attribute ¶

key_ops instance-attribute ¶

kid instance-attribute ¶

kty instance-attribute ¶

use instance-attribute ¶

x5c instance-attribute ¶

x5t instance-attribute ¶

x5t_S256 instance-attribute ¶

x5u instance-attribute ¶

JWKEC ¶

crv instance-attribute ¶

d instance-attribute ¶

kty instance-attribute ¶

x instance-attribute ¶

y instance-attribute ¶

JWKOct ¶

k instance-attribute ¶

kty instance-attribute ¶

JWKRSA ¶

d instance-attribute ¶

dp instance-attribute ¶

dq instance-attribute ¶

e instance-attribute ¶

kty instance-attribute ¶

n instance-attribute ¶

p instance-attribute ¶

q instance-attribute ¶

qi instance-attribute ¶

JWKSet ¶

filter ¶

from_dict classmethod ¶

get_by_kid ¶

get_by_kty ¶

to_dict ¶

JWKDict `module-attribute` ¶

alg `property` ¶

kid `property` ¶

kty `property` ¶

from_dict `classmethod` ¶

validate `staticmethod` ¶

alg `instance-attribute` ¶

key_ops `instance-attribute` ¶

kid `instance-attribute` ¶

kty `instance-attribute` ¶

use `instance-attribute` ¶

x5c `instance-attribute` ¶

x5t `instance-attribute` ¶

x5t_S256 `instance-attribute` ¶

x5u `instance-attribute` ¶

crv `instance-attribute` ¶

d `instance-attribute` ¶

kty `instance-attribute` ¶

x `instance-attribute` ¶

y `instance-attribute` ¶

k `instance-attribute` ¶

kty `instance-attribute` ¶

d `instance-attribute` ¶

dp `instance-attribute` ¶

dq `instance-attribute` ¶

e `instance-attribute` ¶

kty `instance-attribute` ¶

n `instance-attribute` ¶

p `instance-attribute` ¶

q `instance-attribute` ¶

qi `instance-attribute` ¶

from_dict `classmethod` ¶