support for `JOSE` (Javascript Object Signing and Encryption)

[sandros94]

This all started while doing some considerations for nuxt-auth-utils, but soon realized this could be easily implemented upstream, here.

Essentially, my idea is to introduce a new utility to manage JOSEs (Javascript Object Signing and Encryption), more commonly referred to JWT, although it is only one of them.

A simple definition about them is from a this stackoverflow answer:

JOSE stands for JSON Object Signing and Encryption. It's a set of standards used to sign and encrypt data using JSON-based data structures. In other words, JWA, JWE, JWK, JWS, and JWT are all part of JOSE.

TL;DR:

• JWA: Defines a set of crypto algorithms and identifiers used in JWE, JWK and JWS.
• JWK: Defines a representation of crypto keys used as input for the algorithms defined in JWA using JSON-based data structures.
• JWE: Defines encrypted content using JSON-based data structures. The encryption/decryption is performed with the algorithms defined in JWA.
• JWS: Defines signed content using JSON-based data structures. The signing/verification is performed with the algorithms defined in JWA
• JWT: Defines subject claims using JSON-based data structures. The claims can be optionally protected via JWE or JWS.

[...]

Going more indepth

Quick disclaimer: I haven't finished reading all RFCs (JWA, JWK, JWT, JWS, JWE), as I started this topic only recently and it is quite a read 😰...

Each one does not exclude the other, in fact most of the use for JWT is based on a combination of JWA, JWK, JWS/JWE. What they have in common is the data structure and their encoding.

For example a general JWT has the <header>.<payload> structure, each section being base64 encoded and separated with periods (.). Both sections are in plain text, meaning that parsing the base64 will return the original objects with their content. There are a number of predefined claims, taking in example the payload ones we could have available information like iss (identifies the JWT issuer), sub (identifies the subject the JWT is for), exp (yes, expiration time) and others. Then we can have other data that is project specific and might be encrypted by the server.

At this point you might ask yourself "but how can I make sure that third parties do not change the data on their own? Since it is stored plain-text"

*JWS enters the chat*

With JWS (JSON Web Signature) in addition to <header>.<payload> we can add another section at the end .<signature>, generated by applying a cryptographic algorithm to the base64-encoded header and payload (the specific algorithm is declared in the header). ofc a private key is required in this process and a public key for verification in a asymmetric case, while something like HS256 for symmetric cases. If the signature is invalid then it is clear that an attempt of forgery/tampering has taken place, and the JWT must be rejected.

But what if I don't want the client to be able to read any data?
I'm glad you asked: This is the case for JWE, where its structure is more like <header>.<ecrypted>.

With JWE (JSON Web Encryption) the payload is fully encrypted, while the header, as always, keeps information about encryption process and metadata. Essentially a useSession but with an additional base64 header in front.

Personal notes

As far as I see it we should mainly be interested in JWT, JWS and JWE, as JWA and JWK are already used internally by them.

All JWT variants can hold more sections than those I described, all delimited by periods in the same cookie value. What is common is that some of these sections are plain text encoded in base64, so that any system is allowed to quickly understand which variant they are dealing with (for example JWS or JWE) and which cryptography should be used (if available).

WDYT? useJOSE or useJWT?

Additional information

• Would you be willing to help implement this feature?

[sandros94]

Ideally we would update useSession to be based on JWE just by deprecating iron-crypto and writing a standard JWE content (potentially making the sealed content even smaller in normal use-cases):

o JOSE Header
o JWE Encrypted Key
o JWE Initialization Vector
o JWE AAD
o JWE Ciphertext
o JWE Authentication Tag

keeping in mind that as a bare minimum only header and ciphertext will be populated

[sandros94]

I've decided to close both this issue and related PR (#997)

Original comment:

I've been considering doing this for so long now, but ended up writing the underlying reason only now in a different PR (here and the comment right after)

But essentially: the current Iron Crypto implementation, while not my favorite, is good enough for the general use that it offers and perfectly covers. While JWE, and those specs that build upon it, does require some changes that may disrupt too many in the community. Not to mention that at the current state the JWE implementation is lacking many aspects that I've learned in the months after.

For those that are interested in supporting JWT in their h3 projects, feel free to take a look at unjwt which also offers adapters for h3 like useJWESession and useJWSSession.