Konubinix' opinionated web of thoughts

JSON Web Signature


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


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.


Unsecured JWS

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


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


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


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.


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


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


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.


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.


jws signature

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


JWS Compact Serialization

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


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


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

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


Notes linking here