JWS API#

This part of the documentation covers all the interfaces of joserfc.jws.

class joserfc.jws.CompactSignature(protected: dict[str, Any], payload: bytes)#

JSON Web Signature object for compact mode. This object is used to represent the JWS instance.

headers() → dict[str, Any]#: Returns protected header values in dict.

payload#: payload content in bytes

protected#: protected header

final class joserfc.jws.FlattenedJSONSerialization#

class joserfc.jws.FlattenedJSONSignature(member: HeaderMember, payload: bytes)#

JSON Signature object that represents a flattened JSON serialization.

flattened: ClassVar[bool] = True#: mark it as flattened

headers() → dict[str, Any]#: Header values in dict.

member: HeaderMember#: the only header member

property members: list[HeaderMember]#: A list of header members. For flattened JSON serialization, there will be only one header member.

payload: bytes#: payload content in bytes

final class joserfc.jws.GeneralJSONSerialization#

class joserfc.jws.GeneralJSONSignature(members: list[HeaderMember], payload: bytes)#

JSON Signature object that represents a general JSON serialization.

flattened: ClassVar[bool] = False#: mark it as not flattened (general)

members: list[HeaderMember]#: a list of header members

payload: bytes#: payload content in bytes

class joserfc.jws.HeaderDict#

class joserfc.jws.HeaderMember(protected: dict[str, Any] | None = None, header: dict[str, Any] | None = None)#

A header member of the JSON signature. It is combined with protected header, and unprotected header.

header#: unprotected header

protected#: protected header

class joserfc.jws.JWSRegistry(header_registry: dict[str, HeaderParameter] | None = None, algorithms: Collection[str] | None = None, strict_check_header: bool = True)#

A registry for JSON Web Signature to keep all the supported algorithms. An instance of JWSRegistry is usually used together with methods in joserfc.jws.

Parameters:

header_registry – extra header parameters registry
algorithms – allowed algorithms to be used
strict_check_header – only allow header key in the registry to be used

class Strategy(*values)#

RECOMMENDED = 1#: find the recommended algorithm

SECURITY = 2#: find the most secure algorithm

check_header(header: dict[str, Any]) → None#: Check and validate the fields in header part of a JWS object.

classmethod filter_algorithms(key: Any, names: list[str] | None = None) → list[JWSAlgModel]#

Filter JWS algorithms based on the given algorithm names.

Parameters:

key – a key instance or a KeySet
names – list of algorithm names

get_alg(name: str) → JWSAlgModel#

Get the allowed algorithm instance of the given name.

Parameters:: name – value of the alg, e.g. HS256, RS256

classmethod guess_algorithm(key: Any, strategy: Strategy) → JWSAlgModel | None#

Guess the JWS algorithm for a given key.

Parameters:

key – key instance or a KeySet
strategy – the strategy for guessing the JWS algorithm

max_header_length: int = 512#: max header content’s size in bytes

max_payload_length: int = 128000#: max payload content’s size in bytes

max_signature_length: int = 1024#: max signature’s size in bytes

classmethod register(alg: JWSAlgModel) → None#: Register a given JWS algorithm instance to the registry.

Extract and validate the JWS Compact Serialization (in string, or bytes) with the given key. An JWE Compact Serialization looks like:

line breaks for display purposes only#

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Parameters:

value – a string (or bytes) of the JWS Compact Serialization
public_key – a flexible public key to verify the signature
algorithms – a collection (list, tuple, or set) of allowed algorithms
registry – a JWSRegistry to use
payload – optional payload, required with detached content

Raises:

BadSignatureError – when signature verification fails

Returns:

object of the CompactSignature

Extract and validate the JWS (in string) with the given key.

Parameters:

value – a dict of the JSON signature
public_key – a flexible public key to verify the signature
algorithms – a collection (list, tuple, or set) of allowed algorithms
registry – a JWSRegistry to use

Returns:

object of GeneralJSONSignature or FlattenedJSONSignature

Raises:

BadSignatureError – when signature verification fails

joserfc.jws.detach_content(value: str) → str#

joserfc.jws.detach_content(value: GeneralJSONSerialization) → dict[str, Any]

joserfc.jws.detach_content(value: FlattenedJSONSerialization) → dict[str, Any]

In some contexts, it is useful to integrity-protect content that is not itself contained in a JWS. This method is an implementation of https://www.rfc-editor.org/rfc/rfc7515#appendix-F

It is used to detach the content of the compact and JSON serialization.

>>> from joserfc import jws
>>> from joserfc.jwk import OctKey
>>> key = OctKey.import_key("secret")
>>> encoded_text = jws.serialize_compact({"alg": "HS256"}, b"hello", key)
>>> jws.detach_content(encoded_text)
'eyJhbGciOiJIUzI1NiJ9..UYmO_lPAY5V0Wf4KZsfhiYs1SxqXPhxvjuYqellDV5A'

You can also detach the JSON serialization:

>>> obj = jws.serialize_json({"protected": {"alg": "HS256"}}, b"hello", key)
>>> jws.detach_content(obj)
{
    'payload': '',
    'signature': 'UYmO_lPAY5V0Wf4KZsfhiYs1SxqXPhxvjuYqellDV5A',
    'protected': 'eyJhbGciOiJIUzI1NiJ9'
}

joserfc.jws.extract_compact(value: bytes, payload: bytes | str | None = None, registry: JWSRegistry | None = None) → CompactSignature#

Extract the JWS Compact Serialization from bytes to object.

Parameters:

value – JWS in bytes
payload – optional payload, required with detached content
registry – optional JWSRegistry instance

Raises:

DecodeError – when decoding fails

Generate a JWS Compact Serialization. The JWS Compact Serialization represents digitally signed or MACed content as a compact, URL-safe string, per Section 7.1.

BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload) || '.' ||
BASE64URL(JWS Signature)

Parameters:

protected – protected header part of the JWS, in dict
payload – payload data of the JWS, in bytes
private_key – a flexible private key to sign the signature
algorithms – a collection (list, tuple, or set) of allowed algorithms
registry – a JWSRegistry to use

Returns:

JWS in str

Generate a JWS JSON Serialization (in dict). The JWS JSON Serialization represents digitally signed or MACed content as a JSON object. This representation is neither optimized for compactness nor URL-safe.

A general JWS JSON Serialization contains:

payload: The “payload” member MUST be present and contain the value BASE64URL(JWS Payload).
signatures: The “signatures” member value MUST be an array of JSON objects. Each object represents a signature or MAC over the JWS Payload and the JWS Protected Header.

A flatten JWS JSON Serialization looks like:

{
    "payload":"<payload contents>",
    "protected":"<integrity-protected header contents>",
    "header":<non-integrity-protected header contents>,
    "signature":"<signature contents>"
}

Validate the JWS Compact Serialization with the given key. This method is usually used together with extract_compact.

Parameters:

obj – object of the JWS Compact Serialization
public_key – a flexible public key to verify the signature
algorithms – a collection (list, tuple, or set) of allowed algorithms
registry – a JWSRegistry to use