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.