Konubinix' opinionated web of thoughts

JSON Web Signature

Fleeting

JSON Web Signature (JWS)
A data structure representing a digitally signed or MACed message.

— https://datatracker.ietf.org/doc/html/rfc7515

JWS JSON Serialization
A representation of the JWS as a JSON object. Unlike the JWS Compact Serialization, the JWS JSON Serialization enables multiple digital signatures and/or MACs to be applied to the same content. This representation is neither optimized for compactness nor URL-safe.

— https://datatracker.ietf.org/doc/html/rfc7515

Unsecured JWS

A JWS that provides no integrity protection. Unsecured JWSs use the “alg” value “none”.

— https://datatracker.ietf.org/doc/html/rfc7515

A JWS represents these logical values (each of which is defined in Section 2):

— https://datatracker.ietf.org/doc/html/rfc7515#section-3

two serializations for JWSs:

  • a compact, URL-safe serialization called the JWS Compact Serialization
  • and a JSON serialization called the JWS JSON Serialization.

The JWS Compact Serialization is a compact, URL-safe representation intended for space constrained environments such as HTTP Authorization headers and URI query parameters

— https://datatracker.ietf.org/doc/html/rfc7515

JWS does not use exactly base64

In both serializations, the JWS Protected Header, JWS Payload, and JWS Signature are base64url encoded, since JSON lacks a way to directly represent arbitrary octet sequences.

— https://datatracker.ietf.org/doc/html/rfc7515#section-3

the number of ‘=’ padding characters that needs to be added to the end of a base64url encoded string without padding to turn it into one with padding is a deterministic function of the length of the encoded string

— https://datatracker.ietf.org/doc/html/rfc7515

s = s.Replace(’+’, ‘-’); / 62nd char of encoding s = s.Replace(’’, ‘_’); // 63rd char of encoding

— https://datatracker.ietf.org/doc/html/rfc7515

how to decode JWS pseudo base64?

As stated in the appendix C, they don’t provide base64 padding, hence we artificially add an extra padding of “=” to make python implementation accept those base64 encoded content. Also, they replace the + and / character of the base64 alphabet respectively with - and _. This makes sense, as this content will eventually be put into a URL, but one could ask why not using a more URL friendly encoding, like base58 or base32.

Therefore the python code to read such data should be like:

import base64
def base64decode(content):
    return base64.b64decode(content.replace("-", "+").replace("_", "/") + "===")

def base64encode(content):
    return base64.b64encode(content).replace(b"+", b"-").replace(b"/", b"_").rstrip(b"=")

JOSE header

JOSE header is defined in JWS (in here) and JWE (in here). It is a standard of encoding in json the information about how to use the JWS or JWE payload. It contains the type of the payload and the signature/encryption algorithms and hashes to use.

JOSE Header
JSON object containing the parameters describing the cryptographic operations and parameters employed. The JOSE Header is comprised of a set of Header Parameters.

— https://datatracker.ietf.org/doc/html/rfc7515

typ

jws payload

JWS Payload The sequence of octets to be secured – a.k.a., the message. The payload can contain an arbitrary sequence of octets.

— https://datatracker.ietf.org/doc/html/rfc7515

jws signature

JWS Signature Digital signature or MAC over the JWS Protected Header and the JWS Payload

— https://datatracker.ietf.org/doc/html/rfc7515

JWS Compact Serialization

JWS Compact Serialization
A representation of the JWS as a compact, URL-safe string

— https://datatracker.ietf.org/doc/html/rfc7515

In the JWS Compact Serialization, no JWS Unprotected Header is used

— https://datatracker.ietf.org/doc/html/rfc7515#section-3

In the JWS Compact Serialization, a JWS is represented as the concatenation:

BASE64URL(UTF8(JWS Protected Header)) || ‘.’ || BASE64URL(JWS Payload) || ‘.’ || BASE64URL(JWS Signature)

— https://datatracker.ietf.org/doc/html/rfc7515#section-3

Notes linking here