11 JSON Object Signing and Encryption (JOSE)

Modern systems exchange data across languages, teams, and organizations, so shared, well-specified formats are essential for secure interoperability. The JOSE family of standards provides exactly that for JSON-based signing and encryption. JSON Web Algorithms (JWA) standardizes names for cryptographic algorithms, while JSON Web Key (JWK) expresses secret, public, and private keys as JSON. On top of these, JSON Web Signature (JWS) secures content against tampering and proves authenticity, and JSON Web Encryption (JWE) protects confidentiality and integrity of arbitrary byte payloads. Understanding these formats not only simplifies implementation but also makes troubleshooting and cross-platform integration far easier.

JWS packages three elements—header, payload, and signature—into a compact, Base64URL-encoded, dot-separated string that is safe for HTTP headers and URLs. The header declares the signing algorithm via a JWA identifier (for example, HS256), the payload holds arbitrary data, and the signature is either a MAC or a digital signature, providing integrity and authenticity (not confidentiality). Libraries like Nimbus streamline creation and verification, as illustrated by the ACME refunds scenario where JWS replaces ad hoc file-plus-checksum exchanges with a single, self-describing artifact. A critical implementation pitfall is the alg:none vulnerability; developers must explicitly reject unsigned tokens to prevent signature bypass.

JWE extends the model to deliver confidentiality with authenticated encryption, typically using AES-GCM. Its compact form includes a header, an optional encrypted content-encryption key, the ciphertext, and an authentication tag (with an initialization vector conveyed alongside). Direct encryption (alg: dir) omits the encrypted key when parties already share it. With JOSE-aware libraries, encryption and decryption become straightforward and interoperable without bespoke metadata handling. In terms of goals, JWS provides integrity and authenticity, while JWE adds confidentiality; symmetric variants do not provide non-repudiation. Finally, JSON Web Token (JWT) is a constrained use of JWS or JWE where the payload must be a JSON object with standardizable claims, a format widely used in identity protocols but sometimes criticized for flexible options that can be misconfigured if care isn’t taken.

Relationship between the standards that are part of the JSON Object Signing and Encryption (JOSE) suite. JOSE enables interoperability between applications that want to exchange encrypted or signed data using the JSON data format. JOSE standards are used extensively by popular security protocols such as OpenID Connect for Single Sign On.

ACME Inc. staff approve refunds using the warehouse management application. Once a day the warehouse management application generates a refunds.json file. The payment service refunds customer credit cards for the amount specified in the refunds.json file.

The logical structure of a JSON Web Signature (JWS). A JSON metadata header describing the type of signature used. A payload that can be any type of data format not just JSON. Signature to use verify that the header and payload were not tampered with. A JWS payload is always readable to anyone who can access the JWS object.

Road from data to a JWS. A JSON Web Signature (JWS) object can be safely embedded in a URL or HTTP headers because it is represented a base64 URL string where each component is separated by a dot.

Parts of a JSON Web Encryption (JWE) object.

A JSON web token (JWT) can be a JWS object with the added restriction that the payload must be JSON object.

The collection of standards. JSON Web Token (JWT) builds on top of the JWE and JWS standards. JWT is the token format for the OpenID Connect standard.

• JSON Object Signing and Encryption (JOSE) is suite of standards used to represent cryptographic algorithms, keys, signed content, and encrypted content as JSON objects.
• JOSE is widely used with excellent support in many programming languages. However, it has come in some criticism due to unnecessary complexity in the standard that make it easy to misuse. Watch out for the JWS alg:none vulnerability in any application or library you are using.
• JSON Web Signature (JWS) is an industry standard data format for signed data, it has JSON metadata header, a payload that can have any format, and a signature to validate the payload and header were not tampered with.
• JWS support signatures with message authentication codes (MACs) which we covered in this chapter and digital signatures which we will cover in a future chapter.
• JSON Web Encryption (JWE) is an industry standard data format for representing encrypted data in JSON. It supports AES and has a lot of implementations in different programming languages.
• JSON Web Key (JWK) used to represent cryptographic keys as JSON objects.
• JSON Web Algorithm (JWA) used to define the various algorithms used by JWS, JWE, and JWK.
• Always consult with your Information Security team to make sure you are using corporate recommended configurations of common cryptographic algorithms.
• The examples in this book are optimized for educational value, they take shortcuts to make the code fit on the page, and to emphasis the concepts. Don’t copy and paste the sample code blindly, you must make it production ready before you use it.

FAQ