1# github.com/lestrrat-go/jwx  [](https://pkg.go.dev/github.com/lestrrat-go/jwx) [](http://codecov.io/github/lestrrat-go/jwx?branch=main)
2
3Various libraries implementing various JWx technologies. Please click on the package names in the table below to find the synopsis/description for each package.
4
5If you are using this module in your product or your company, please add your product and/or company name in the [Wiki](https://github.com/lestrrat-go/jwx/wiki/Users)! It really helps keeping up our motivation.
6
7| Package name | Notes |
8|-----------------------------------------------------------|-------------------------------------------------|
9| [jwt](https://github.com/lestrrat-go/jwx/tree/main/jwt) | [RFC 7519](https://tools.ietf.org/html/rfc7519) |
10| [jwk](https://github.com/lestrrat-go/jwx/tree/main/jwk) | [RFC 7517](https://tools.ietf.org/html/rfc7517) + [RFC 7638](https://tools.ietf.org/html/rfc7638) |
11| [jwa](https://github.com/lestrrat-go/jwx/tree/main/jwa) | [RFC 7518](https://tools.ietf.org/html/rfc7518) |
12| [jws](https://github.com/lestrrat-go/jwx/tree/main/jws) | [RFC 7515](https://tools.ietf.org/html/rfc7515) + [RFC 7797](https://tools.ietf.org/html/rfc7797) |
13| [jwe](https://github.com/lestrrat-go/jwx/tree/main/jwe) | [RFC 7516](https://tools.ietf.org/html/rfc7516) |
14
15# How to Use
16
17* [API documentation](https://pkg.go.dev/github.com/lestrrat-go/jwx)
18* [How-to style documentation](./docs)
19* [Runnable Examples](./examples)
20
21# Description
22
23## History
24
25My goal was to write a server that heavily uses JWK and JWT. At first glance
26the libraries that already exist seemed sufficient, but soon I realized that
27
281. To completely implement the protocols, I needed the entire JWT, JWK, JWS, JWE (and JWA, by necessity).
292. Most of the libraries that existed only deal with a subset of the various JWx specifications that were necessary to implement their specific needs
30
31For example, a certain library looks like it had most of JWS, JWE, JWK covered, but then it lacked the ability to include private claims in its JWT responses. Another library had support of all the private claims, but completely lacked in its flexibility to generate various different response formats.
32
33Because I was writing the server side (and the client side for testing), I needed the *entire* JOSE toolset to properly implement my server, **and** they needed to be *flexible* enough to fulfill the entire spec that I was writing.
34
35So here's `github.com/lestrrat-go/jwx`. This library is extensible, customizable, and hopefully well organized to the point that it is easy for you to slice and dice it.
36
37## Why would I use this library?
38
39There are several other major Go modules that handle JWT and related data formats,
40so why should you use this library?
41
42From a purely functional perspective, the only major difference is this:
43Whereas most other projects only deal with what they seem necessary to handle
44JWTs, this module handles the **_entire_** spectrum of JWS, JWE, JWK, and JWT.
45
46That is, if you need to not only parse JWTs, but also to control JWKs, or
47if you need to handle payloads that are NOT JWTs, you should probably consider
48using this module. You should also note that JWT is built _on top_ of those
49other technologies. You simply cannot have a complete JWT package without
50implementing the entirety of JWS/JWS/JWK, which this library does.
51
52Next, from an implementation perspective, this module differs significantly
53from others in that it tries very hard to expose only the APIs, and not the
54internal data. For example, individual JWT claims are not accessible through
55struct field lookups. You need to use one of the getter methods.
56
57This is because this library takes the stance that the end user is fully capable
58and even willing to shoot themselves on the foot when presented with a lax
59API. By making sure that users do not have access to open structs, we can protect
60users from doing silly things like creating _incomplete_ structs, or access the
61structs concurrently without any protection. This structure also allows
62us to put extra smarts in the structs, such as doing the right thing when
63you want to parse / write custom fields (this module does not require the user
64to specify alternate structs to parse objects with custom fields)
65
66In the end I think it comes down to your usage pattern, and priorities.
67Some general guidelines that come to mind are:
68
69* If you want a single library to handle everything JWx, such as using JWE, JWK, JWS, handling [auto-refreshing JWKs](https://github.com/lestrrat-go/jwx/blob/main/docs/04-jwk.md#auto-refreshing-remote-keys), use this module.
70* If you want to honor all possible custom fields transparently, use this module.
71* If you want a standardized clean API, use this module.
72
73Otherwise, feel free to choose something else.
74
75# Command Line Tool
76
77Since v1.1.1 we have a command line tool `jwx` (*). With `jwx` you can create JWKs (from PEM files, even), sign and verify JWS message, encrypt and decrypt JWE messages, etc.
78
79(*) Okay, it existed since a long time ago, but it was never useful.
80
81## Installation
82
83```
84go install github.com/lestrrat-go/jwx/cmd/jwx
85```
86
87# Caveats
88
89## Backwards Compatibility Notice
90
91### Users of github.com/lestrrat/go-jwx
92
93Uh, why are you using such an ancient version? You know that repository is archived for a reason, yeah? Please use the new version.
94
95### Pre-1.0.0 users
96
97The API has been reworked quite substantially between pre- and post 1.0.0 releases. Please check out the [Changes](./Changes) file (or the [diff](https://github.com/lestrrat-go/jwx/compare/v0.9.2...v1.0.0), if you are into that sort of thing)
98
99### v1.0.x users
100
101The API has gone under some changes for v1.1.0. If you are upgrading, you might want to read the relevant parts in the [Changes](./Changes) file.
102
103# Contributions
104
105## Issues
106
107For bug reports and feature requests, please try to follow the issue templates as much as possible.
108For either bug reports or feature requests, failing tests are even better.
109
110## Pull Requests
111
112Please make sure to include tests that excercise the changes you made.
113
114If you are editing auto-generated files (those files with the `_gen.go` suffix, please make sure that you do the following:
115
1161. Edit the generator, not the generated files (e.g. internal/cmd/genreadfile/main.go)
1172. Run `make generate` (or `go generate`) to generate the new code
1183. Commit _both_ the generator _and_ the generated files
119
120## Discussions / Usage
121
122Please try [discussions](https://github.com/lestrrat-go/jwx/discussions) first.
123
124# Related Modules
125
126* [github.com/jwx-go/crypto-signer/gcp](https://github.com/jwx-go/crypto-signer/tree/main/gcp) - GCP KMS wrapper that implements [`crypto.Signer`](https://pkg.go.dev/crypto#Signer)
127* [github.com/jwx-go/crypto-signer/aws](https://github.com/jwx-go/crypto-signer/tree/main/aws) - AWS KMS wrapper that implements [`crypto.Signer`](https://pkg.go.dev/crypto#Signer)
128
129# Credits
130
131* Initial work on this library was generously sponsored by HDE Inc (https://www.hde.co.jp)
132* Lots of code, especially JWE was taken from go-jose library (https://github.com/square/go-jose)
133* Lots of individual contributors have helped this project over the years. Thank each and everyone of you very much.
134
View as plain text