JWE

Contents

• Primer
• Usage

Primer

A JSON Web Encryption (JWE) represents encrypted content. It provides confidentiality and optionally integrity protection for this content JWE consists of:

1. A JSON-based header
2. An encrypted content encryption key
3. An initialization vector
4. Some additional authenticated data
5. The ciphertext
6. An authentication tag

To understand a JWE, it is good to understand the way it encrypts its payload.

As you may have noticed, a JWE contains two encrypted parts. The encrypted content encryption key and the ciphertext. When you construct a JWE, you have to provide the public key of the JWE’s recipient. During initialization, a shared content encryption key is created. The provided payload is then encrypted using this key, yielding the ciphertext. The shared content encryption key is then encrypted using the recipient’s public key and included in the JWE.

The recipient can use his matching private key to decrypt the encrypted content encryption key. Using this decrypted key he can decrypt the ciphertext and read the JWE payload.

Click here for a visualization of the JWE encryption and decryption flow.

  Provided By You         Computed Internally                     JWE                               Recipient


 +-------------+                                            +---------------+                                +-------------+
 |             |                                            |               |                                |             |
 |   Payload   +------------------^------------------------->  Ciphertext   +---------------------------^----+   Payload   |
 |             |                  |                         |               |                           |    |             |
 +-------------+                  |                         +---------------+                           |    +-------------+
                         encrypts |                                                            decrypts |
                                  |                                                                     |
                                  |                                                                     |
                    +-------------+--------------+     +----------------------------+     +-------------+--------------+
                    |                            |     |                            |     |                            |
                    |           Shared           +--^-->         Encrypted          +--^-->           Shared           |
                    |   Content Encryption Key   |  |  |   Content Encryption Key   |  |  |   Content Encryption Key   |
                    |                            |  |  |                            |  |  |                            |
                    +----------------------------+  |  +----------------------------+  |  +----------------------------+
                                                    |                                  |
                                                    |                                  |
                                                    |                                  |
+----------------+              encrypts            |                                  |  decrypts  +-----------------+
|                |                                  |                                  |            |                 |
|   Public Key   +----------------------------------+                                  +------------+   Private Key   |
|                |                                                                                  |                 |
+----------------+                                                                                  +-----------------+

Don’t worry though, most of this logic and the associated values are constructed under the hood. You’ll not have to worry about them too much. Nonetheless, they are described in more detail in the following sections.

Header

The JWE Header is a JSON object specifying the encryption algorithms applied to the payload and the content encryption key. Optionally it can contain additional properties of the JWE.

Example

The following header specifies two algorithms. The JWE’s payload is encrypted using the AES_256_CBC_HMAC_SHA_512 algorithm, yielding the ciphertext. The shared key, with which this payload encryption is performed is encrypted using the RSAES-PKCS1-v1_5 algorithm and included in the JWE.

{ "alg": "RSA1_5", "enc": "A256CBC-HS512" }

A detailed list describing possible header parameters can be found here.