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.

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

member¶: the only header member

payload¶: payload content

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¶: a list of header members

payload¶: payload content

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.JWSAlgModel¶

Interface for JWS algorithm. JWA specification (RFC7518) SHOULD implement the algorithms for JWS with this base implementation.

abstract sign(msg: bytes, key: Any) → bytes¶

Sign the text msg with a private/sign key.

Parameters:

msg – message bytes to be signed
key – private key to sign the message

Returns:

bytes

abstract verify(msg: bytes, sig: bytes, key: Any) → bool¶

Verify the signature of text msg with a public/verify key.

Parameters:

msg – message bytes to be signed
sig – result signature to be compared
key – public key to verify the signature

Returns:

boolean

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

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

Extract the JWS Compact Serialization from bytes to object.

Parameters:: value – JWS in bytes
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