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

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

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: list[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

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

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 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 list of allowed algorithms
registry – a JWSRegistry to use
payload – optional payload, required with detached content

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 list of allowed algorithms
registry – a JWSRegistry to use

Returns:

object of the SignatureData

Raise:

ValueError or BadSignatureError

joserfc.jws.detach_content(value: DetachValue) → DetachValue¶

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) → CompactSignature¶

Extract the JWS Compact Serialization from bytes to object.

Parameters:

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

Raise:

DecodeError

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 list 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 list of allowed algorithms
registry – a JWSRegistry to use