Skip to content

Latest commit

 

History

History
193 lines (137 loc) · 10.5 KB

README.md

File metadata and controls

193 lines (137 loc) · 10.5 KB
Raw

github.com/lestrrat-go/jwx Go Reference codecov.io

Implementation of various JWx technologies

Package name Notes
jwt RFC 7519
jwk RFC 7517 + RFC 7638
jwa RFC 7518
jws RFC 7515
jwe RFC 7516

Why?

My goal was to write a server that heavily uses JWK and JWT. At first glance the libraries that already exist seemed sufficient, but soon I realized that

  1. To completely implement the protocols, I needed the entire JWT, JWK, JWS, JWE (and JWA, by necessity).
  2. Most of the libraries that existed only deal with a subset of the various JWx specifications that were necessary to implement their specific needs

For 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.

Because 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.

So 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.

Notes for users of pre-1.0.0 release

The API has been reworked quite substantially between pre- and post 1.0.0 releases. Please check out the Changes file (or the diff, if you are into that sort of thing)

Packages

JWA Go Reference

Package github.com/lestrrat-go/jwx/jwa defines the various algorithm described in RFC7518

JWT Go Reference

Package github.com/lestrrat-go/jwx/jwt implements JSON Web Tokens as described in RFC7519.

  • Convenience methods for oft-used keys ("aud", "sub", "iss", etc)
  • Ability to Get/Set arbitrary keys
  • Conversion to and from JSON
  • Generate signed tokens
  • Verify signed tokens
  • Extra support for OpenID tokens via github.com/lestrrat-go/jwx/jwt/openid

Examples are located in the examples directory (jwt_example_test.go)

JWK Go Reference

Package github.com/lestrrat-go/jwx/jwk implements JWK as described in RFC7517

  • Parse and work with RSA/EC/Symmetric/OKP JWK types
    • Convert to and from JSON
    • Convert to and from raw key types (e.g. *rsa.PrivateKey)
  • Ability to keep a JWKS fresh.
  • Add arbitrary fields in the JWK object

Examples are located in the examples directory (jwk_example_test.go)

Supported key types:

kty Curve Go Key Type
RSA N/A rsa.PrivateKey / rsa.PublicKey (2)
EC P-256
P-384
P-521		 ecdsa.PrivateKey / ecdsa.PublicKey (2)
oct N/A []byte
OKP Ed25519 (1) ed25519.PrivateKey / ed25519.PublicKey (2)
X25519 (1) (jwx/)x25519.PrivateKey / x25519.PublicKey (2)
  • Note 1: Experimental
  • Note 2: Either value or pointers accepted (e.g. rsa.PrivateKey or *rsa.PrivateKey)

JWS Go Reference

Package github.com/lestrrat-go/jwx/jws implements JWS as described in RFC7515

  • Parse and generate compact or JSON serializations
  • Sign and verify arbitrary payload
  • Use any of the keys supported in github.com/lestrrat-go/jwx/jwk
  • Add arbitrary fields in the JWS object
  • Ability to add/replace existing signature methods

Examples are located in the examples directory (jws_example_test.go)

Supported signature algorithms:

Algorithm Supported? Constant in jwa
HMAC using SHA-256 YES jwa.HS256
HMAC using SHA-384 YES jwa.HS384
HMAC using SHA-512 YES jwa.HS512
RSASSA-PKCS-v1.5 using SHA-256 YES jwa.RS256
RSASSA-PKCS-v1.5 using SHA-384 YES jwa.RS384
RSASSA-PKCS-v1.5 using SHA-512 YES jwa.RS512
ECDSA using P-256 and SHA-256 YES jwa.ES256
ECDSA using P-384 and SHA-384 YES jwa.ES384
ECDSA using P-521 and SHA-512 YES jwa.ES512
RSASSA-PSS using SHA256 and MGF1-SHA256 YES jwa.PS256
RSASSA-PSS using SHA384 and MGF1-SHA384 YES jwa.PS384
RSASSA-PSS using SHA512 and MGF1-SHA512 YES jwa.PS512
EdDSA (1) YES jwa.EdDSA
  • Note 1: Experimental

JWE Go Reference

Package github.com/lestrrast-go/jwx/jwe implements JWE as described in RFC7516

  • Encrypt and Decrypt arbitrary data
  • Content compression and decompression
  • Add arbitrary fields in the JWE header object

Examples are located in the examples directory (jwe_example_test.go)

Supported key encryption algorithm:

Algorithm Supported? Constant in jwa
RSA-PKCS1v1.5 YES jwa.RSA1_5
RSA-OAEP-SHA1 YES jwa.RSA_OAEP
RSA-OAEP-SHA256 YES jwa.RSA_OAEP_256
AES key wrap (128) YES jwa.A128KW
AES key wrap (192) YES jwa.A192KW
AES key wrap (256) YES jwa.A256KW
Direct encryption YES (1) jwa.DIRECT
ECDH-ES YES (1) jwa.ECDH_ES
ECDH-ES + AES key wrap (128) YES jwa.ECDH_ES_A128KW
ECDH-ES + AES key wrap (192) YES jwa.ECDH_ES_A192KW
ECDH-ES + AES key wrap (256) YES jwa.ECDH_ES_A256KW
AES-GCM key wrap (128) YES jwa.A128GCMKW
AES-GCM key wrap (192) YES jwa.A192GCMKW
AES-GCM key wrap (256) YES jwa.A256GCMKW
PBES2 + HMAC-SHA256 + AES key wrap (128) YES jwa.PBES2_HS256_A128KW
PBES2 + HMAC-SHA384 + AES key wrap (192) YES jwa.PBES2_HS384_A192KW
PBES2 + HMAC-SHA512 + AES key wrap (256) YES jwa.PBES2_HS512_A256KW
  • Note 1: Single-recipient only

Supported content encryption algorithm:

Algorithm Supported? Constant in jwa
AES-CBC + HMAC-SHA256 (128) YES jwa.A128CBC_HS256
AES-CBC + HMAC-SHA384 (192) YES jwa.A192CBC_HS384
AES-CBC + HMAC-SHA512 (256) YES jwa.A256CBC_HS512
AES-GCM (128) YES jwa.A128GCM
AES-GCM (192) YES jwa.A192GCM
AES-GCM (256) YES jwa.A256GCM

Global Settings

Configuring JSON Parsing

If you want to parse numbers in the incoming JSON objects as json.Number instead of floats, you can use the following call to globally affect the behavior of JSON parsing.

func init()
  jwx.DecoderSettings(jwx.WithUseNumber(true))
}

Do be aware that this has global effect. All code that calls in to encoding/json within jwx will use your settings.

Other related libraries:

Contributions

Issues

For bug reports and feature requests, please try to follow the issue templates as much as possible. For either bug reports or feature requests, failing tests are even better.

Pull Requests

Please make sure to include tests that excercise the changes you made.

Discussions / Usage

Please try discussions first.

Credits