# JSON Web Signature

JSON Web Signature.

class josepy.jws.MediaType

  MediaType field encoder/decoder.

  PREFIX = 'application/'

    MIME Media Type and Content Type prefix.

  classmethod decode(value: str) → str

    Decoder.

  classmethod encode(value: str) → str

    Encoder.

class josepy.jws.Header(**kwargs: Any)

  JOSE Header.

  Warning

  This class supports only Registered Header Parameter Names (as defined in section 4.1 of the protocol). If you need Public Header Parameter Names (4.2) or Private Header Parameter Names (4.3), you must subclass and override `from_json()` and `to_partial_json()` appropriately.

  Warning

  This class does not support any extensions through the “crit” (Critical) Header Parameter (4.1.11) and as a conforming implementation, `from_json()` treats its occurrence as an error. Please subclass if you seek for a different behaviour.

  Variables:

    - x5tS256 – “x5t#S256”

    - typ (str) – MIME Media Type, inc. `MediaType.PREFIX`.

    - cty (str) – Content-Type, inc. `MediaType.PREFIX`.

  not_omitted() → Dict[str, Field]

    Fields that would not be omitted in the JSON object.

  find_key() → JWK

    Find key based on header.

    Todo

    Supports only “jwk” header parameter lookup.

    Returns:

      (Public) key found in the header.

    Return type:

      .JWK

    Raises:

      josepy.errors.Error – if key could not be found

class josepy.jws.Signature(**kwargs: Any)

  JWS Signature.

  Variables:

    - combined – Combined Header (protected and unprotected, `Header`).

    - protected (unicode) – JWS protected header (Jose Base-64 decoded).

    - header – JWS Unprotected Header (`Header`).

    - signature (str) – The signature.

  header_cls

    alias of `Header`

  verify(payload: bytes, key: JWK | None = None) → bool

    Verify.

    Parameters:

      - payload (bytes) – Payload to verify.

      - key (JWK) – Key used for verification.

  classmethod sign(payload: bytes, key: JWK, alg: JWASignature, include_jwk: bool = True, protect: FrozenSet = frozenset({}), **kwargs: Any) → Signature

    Sign.

    Parameters:

      - payload (bytes) – Payload to sign.

      - key (JWK) – Key for signature.

      - alg (JWASignature) – Signature algorithm to use to sign.

      - include_jwk (bool) – If True, insert the JWK inside the signature headers.

      - protect (FrozenSet) – List of headers to protect.

  fields_to_partial_json() → Dict[str, Any]

    Serialize fields to JSON.

  classmethod fields_from_json(jobj: Mapping[str, Any]) → Dict[str, Any]

    Deserialize fields from JSON.

class josepy.jws.JWS(**kwargs: Any)

  JSON Web Signature.

  Variables:

    - payload (str) – JWS Payload.

    - signature (str) – JWS Signatures.

  signature_cls

    alias of `Signature`

  verify(key: JWK | None = None) → bool

    Verify.

  classmethod sign(payload: bytes, **kwargs: Any) → JWS

    Sign.

  property signature: Signature

    Get a singleton signature.

    Return type:

      `JWS.signature_cls`

  to_compact() → bytes

    Compact serialization.

    Return type:

      bytes

  classmethod from_compact(compact: bytes) → JWS

    Compact deserialization.

    Parameters:

      compact (bytes) –

  to_partial_json(flat: bool = True) → Dict[str, Any]

    Partially serialize.

    Following the example, partial serialization means the following:

        assert isinstance(Bar().to_partial_json()[0], Foo)
        assert isinstance(Bar().to_partial_json()[1], Foo)

        # in particular...
        assert Bar().to_partial_json() != ['foo', 'foo']

    Raises:

      josepy.errors.SerializationError – in case of any serialization error.

    Returns:

      Partially serializable object.

  classmethod from_json(jobj: Mapping[str, Any]) → JWS

    Deserialize a decoded JSON document.

    Parameters:

      jobj – Python object, composed of only other basic data types, as decoded from JSON document. Not necessarily `dict` (as decoded from “JSON object” document).

    Raises:

      josepy.errors.DeserializationError – if decoding was unsuccessful, e.g. in case of unparseable X509 certificate, or wrong padding in JOSE base64 encoded string, etc.

class josepy.jws.CLI

  JWS CLI.

  classmethod sign(args: Namespace) → None

    Sign.

  classmethod verify(args: Namespace) → bool

    Verify.

  classmethod run(args: List[str] | None = None) → bool | None

    Parse arguments and sign/verify.