JSON Web Signature (JWS) and JWS Detached for a five-year-old.

Tomasz Zwierzchoń
Jul 5, 2019 · 3 min read

Working for some time with JSON Web Signature (JWS) I came to the conclusion that many developers do not understand what it is and how it works.

There are two defined serializations for JWSs: a compact (described in this article) and a JSON.

The compact serialised JWS is a string containing three parts (in order) joined with a dot (“.”):

  • Header,
  • Payload,
  • Signature.

Example of the compact serialised JWS string: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjIyMTgyMzkwMjIsIm5hbWUiOiJUb21hc3ogWndpZXJ6Y2hvxYQifQ.t3VhQ7QsILDuV_HNFSMI-Fb2FoT7fuzalpS5AH8A9c0
Each part is BASE64URL encoded.

The Header describe the digital signature or message authentication code (MAC) applied to the the Payload and optionally additional properties of the JWS.

Header part before encoding is a JSON structure (example below):

{
"alg": "HS256",
"typ": "JWT"
}

The Header parameter names (object keys) within the Header must be unique. There are registered Header parameter names:

  • “alg” (required) — algorithm, which identifies the cryptographic
    algorithm used to secure the JWS;
    It can be set to ‘none’, which indicates that the Signature must be an empty string!
  • “jku” — (optional) JWK Set URL is a URI that refers to a resource for a set of JSON-encoded public keys, one of which corresponds to the key used to digitally sign the JWS;
  • “jwk” — (optional) JSON Web Key is the public key that corresponds to the private key used to digitally sign the JWS. This public key is represented as a JSON Web Key [JWK];
  • “kid” — (optional) key ID is a hint indicating which key was used to secure the JWS. It can be used to inform recipient that key is changed;
  • “x5u” — (optional) X.509 URL is a URI that points to a resource for the X.509 public key certificate or certificate chain corresponding to the private key used to digitally sign the JWS;
  • “x5c” — (optional) X.509 certificate chain contains the X.509 public key certificate or certificate chain corresponding to the private key used to digitally sign the JWS;
  • “x5t” — (optional) X.509 certificate SHA-1 thumbprint (fingerprint) is a
    base64url-encoded SHA-1 thumbprint (a.k.a. digest) of the DER
    encoding of the X.509 public certificate [RFC5280] corresponding to the private key used to digitally sign the JWS;
  • “x5t#S256” — (optional) X.509 certificate SHA-256 thumbprint (fingerprint) is a base64url-encoded SHA-256 thumbprint (a.k.a. digest)
    of the DER encoding of the X.509 public certificate corresponding
    to the private key used to digitally sign the JWS;
  • “typ” — (optional) type is used by JWS applications to declare the media type of the complete JWS;
  • “cty” — (optional) content type is used by JWS applications
    to declare the media type of the Payload.

In our example header, we can see that JWS type is JSON Web Token (JWT) and that Payload is secured by HS256 (HMAC with SHA-256) cryptographic algorithm.

The payload can be any content. It can be JSON but it is not needed.

The signature is computed in the manner defined for the particular algorithm being used (and declared in the Header) from ASCII(BASE64URL(UTF8(JWS Protected Header)) || ‘.’ ||BASE64URL(JWS Payload)).

Important note: Do not confuse BASE64URL with BASE64!
In BASE64URL:

  • all trailing ‘=’ are removed
  • ‘+’ is replaced by ‘-’
  • ‘/’ is replaced by ‘_’.

The HTTP header “x-jws signature” is added, which contains data allowing to check whether the message has not been changed on way from the sender to the recipient.

JWS Detached generation algorithm is very simple:
a) Generate a standard JWS using compact serialization using HTTP body as a payload,
b) Turn the middle part (Payload) into an empty string,
c) Put final string in the HTTP header “x-jws signature”

Example of the JWS Detached string: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..t3VhQ7QsILDuV_HNFSMI-Fb2FoT7fuzalpS5AH8A9c0

Validation HTTP message with JWS Detached is simple too:
a) Get the HTTP header “x-jws signature”,
b) Get BASE64URL HTTP body
c) Put generate string b) into the Payload section
d) Validate JWS

JWS is often found in tandem with JSON Web Token (JWT), JSON Web Encryption (JWE) or JSON Object Signing and Encryption (JOSE). Many similar shortcuts may lead to confusion. In next part we will familiarize with them.

The Startup

Get smarter at building your thing. Join The Startup’s +741K followers.

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +741K followers.

Tomasz Zwierzchoń

Written by

IT Architect. FrontEnd Team Lead. #JavaScript on #IoT #UX #Vue.js Fan. I miss having free time, especially for dancing Tango.

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +741K followers.