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.

joserfc.jws.deserialize_compact(value: bytes | str, public_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWSRegistry | None = None) CompactSignature

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

joserfc.jws.deserialize_json(value: GeneralJSONSerialization, public_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWSRegistry | None = None) GeneralJSONSignature
joserfc.jws.deserialize_json(value: FlattenedJSONSerialization, public_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWSRegistry | None = None) FlattenedJSONSignature

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

joserfc.jws.serialize_compact(protected: Dict[str, Any], payload: bytes | str, private_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWSRegistry | None = None) str

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

joserfc.jws.serialize_json(members: list[HeaderDict], payload: bytes | str, private_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWSRegistry | None = None) GeneralJSONSerialization
joserfc.jws.serialize_json(members: HeaderDict, payload: bytes | str, private_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWSRegistry | None = None) FlattenedJSONSerialization

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>"
}
joserfc.jws.validate_compact(obj: CompactSignature, public_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWSRegistry | None = None) bool

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