1# 1. Anatomy of JOSE and JWX
2
3In this article we will briefly go over what JOSE is, and how each JWX libraries map to the respective RFCs.
4
5---
6
7# JOSE Overview
8
9Javascript Object Signing and Encryption is mainly comprised of specifications that span over 5 RFCs: namely RFC7515, RFC7516, RFC7517, RFC7518, and RFC7519.
10
11* [RFC 7515 - JSON Web Signature (JWS)](https://tools.ietf.org/html/rfc7515)
12* [RFC 7516 - JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516)
13* [RFC 7517 - JSON Web Key (JWK)](https://tools.ietf.org/html/rfc7517)
14* [RFC 7518 - JSON Web Algorithms (JWA)](https://tools.ietf.org/html/rfc7518)
15* [RFC 7519 - JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519)
16
17As there are many RFCs involved, at first it could be daunting. But here is a breakdown for beginners.
18
19While there are other standards and RFCs available related to JOSE such as extensions like ES256K, the above 5 concepts are at the core.
20
21JWX is a Go specific implementation of the JOSE ecosystem, and attempts to do this as cleanly as possible.
22
23# JWT - RFC7519
24
25First, you are probably here because you were trying to work with JWTs, which is described in RFC7519.
26
27JWTs are implemented in github.com/lestrrat-go/jwx/jwt package. There is also a package to deal with OpenID extensions in github.com/lestrrat-go/jwx/jwt/openid.
28
29In its essence, there is nothing special about JWTs: they are just a standardized format to exchange some piece of information.
30
31Most of the times this information must be integrity checked using signatures, securely encrypted, or both.
32
33While they are referenced from RFC7519, the standardized message formats for signed and/or encrypted JWTs are not in the same RFC.
34
35As a side note, many libraries bundle these signature/encryption features into one JWT package, and API becomes tightly coupled with the JWT, which I find confusing and hard to fix/extend- which is part of the reason why JWX was born.
36
37## Documentation for `github.com/lestrrat-go/jwx/jwt`
38
39* [FAQ-style HOW-TOs](./01-jwt.md)
40* [Documentation on pkg.go.dev](https://pkg.go.dev/github.com/lestrrat-go/jwx/jwt)
41
42# JWS - RFC7515
43
44RFC7515 describes JWS, which is used to sign payloads. The format is not necessarily for JWTs: it can sign any arbitrary piece of data.
45
46The signed content can be encoded in two different formats. The most common one is called the compact form, and takes the form of three base64 encoded strings, concatenated by a single period ("."). The other format takes the form of a JSON object.
47
48```
49# An example of a "compact" JWS message
50eyJhbGciOiJFUzI1NiJ9.SGVsbG8sIFdvcmxkCg.3q5N5JyFphiJolUZuBuUZhuWDfmLDR__rZe3lnuaxWe3bfrfvJS9HmUUhie56NqkyN7vjOl8hm6tzJKTc2oNsg
51```
52
53JWS is implemented in github.com/lestrrat-go/jwx/jws package. This package provides ways to sign arbitrary payload into JWS message, and ways to verify them.
54
55## Documentation for `github.com/lestrrat-go/jwx/jws`
56
57* [FAQ-style HOW-TOs](./02-jws.md)
58* [Documentation on pkg.go.dev](https://pkg.go.dev/github.com/lestrrat-go/jwx/jws)
59
60# JWE - RFC7516
61
62RFC7516 describes JWE which is used to encrypt data. Similar to JWS, JWE describes the standardized format to encrypt any arbitrary data, not just JWTs.
63
64And again, similar to JWS, JWE can encode data into two different formats, one of which consists of 5 base64 encoded strings concatenated by a single period ("."). The other format takes the form of a JSON object.
65
66```
67# An example of JWE message
68eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTE5MkdDTSIsImVwayI6eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6IndMckhLNnBTLXZzdmhQZUNfNTN0ZWpxYzZIZUFsMllRWDRmY1hPNGV1bmciLCJ5IjoiV2V3bFdKazJ4QWJYSXE3WFJ6aVlZa2lxMjJfOF9TQ0VsbTA1Vm1iUGhFWSJ9fQ..7UTcbVpz-Ed1Q0wq.sneVfeTeAvzZNSMGpQ.JNo1BbDaKB-Q1mWaBNmdow
69```
70
71JWE is implemented in github.com/lestrrat-go/jwe package. This package provides tools to encrypt payload into JWE messages, and tools to decrypt them.
72
73## Documentation for `github.com/lestrrat-go/jwx/jwe`
74
75* [Documentation on pkg.go.dev](https://pkg.go.dev/github.com/lestrrat-go/jwx/jwe)
76
77# JWK - RFC7517
78
79So JWTs can be signed and/or encrypted using JWS and JWE. However in order to do either operation one needs some sort of a key. This is where RFC757 which describes JWK comes into play.
80
81JWKs describe formats to describe keys, such as RSA keys, Elliptic Curve keys, symmetric keys, etc. Each family of keys have a slightly different, unique format, but they are all encoded as JSON objects.
82
83```
84# An example of a JWK
85{
86 "crv": "P-256",
87 "d": "vVLuV63SADBsZrixRXs3hcteS7SaBrMPnxERz6G1xZ8",
88 "kty": "EC",
89 "x": "uNs7UU1KU9nug9QrfxLmxLtYZLQDnYcX7_J3zkTkhCk",
90 "y": "IGsWjOsDHFbeiQg-Reih-a1BsijmV2RUPPGswl8TRTI"
91}
92```
93
94JWK is implemented in github.com/lestrrat-go/jwx/jwk package. This package provides ways to generate, read, and manipulate JWKs, convert them to and from raw key formats (e.g. "crypto/rsa".PrivateKey to JWK and vice versa). It can also work with PEM-encoded keys.
95
96## Documentation for `github.com/lestrrat-go/jwx/jwk`
97
98* [FAQ-style HOW-TOs](./04-jwk.md)
99* [Documentation on pkg.go.dev](https://pkg.go.dev/github.com/lestrrat-go/jwx/jwk)
100
101# JWA - RFC7518
102
103And finally, RFC exists to define commonly used algorithm names in JWT, JWS, JWE, and JWK.
104
105This is implemented in github.com/lestrrat-go/jwx/jwa.
View as plain text