jwx

README

github.com/lestrrat-go/jwx/v3

Go module implementing various JWx (JWA/JWE/JWK/JWS/JWT, otherwise known as JOSE) technologies.

If you are using this module in your product or your company, please add your product and/or company name in the Wiki! It really helps keeping up our motivation.

Features

• Complete coverage of JWA/JWE/JWK/JWS/JWT, not just JWT+minimum tool set.
  • Supports JWS messages with multiple signatures, both compact and JSON serialization
  • Supports JWS with detached payload
  • Supports JWS with unencoded payload (RFC7797)
  • Supports JWE messages with multiple recipients, both compact and JSON serialization
  • Most operations work with either JWK or raw keys e.g. *rsa.PrivateKey, *ecdsa.PrivateKey, etc).
• Opinionated, but very uniform API. Everything is symmetric, and follows a standard convention
  • jws.Parse/Verify/Sign
  • jwe.Parse/Encrypt/Decrypt
  • Arguments are organized as explicit required parameters and optional WithXXXX() style options.
• Extra utilities
  • jwk.Cache to always keep a JWKS up-to-date
  • bazel-ready

Some more in-depth discussion on why you might want to use this library over others can be found in the Description section

If you are using v0 or v1, you are strongly encouraged to migrate to using v3 (the version that comes with the README you are reading).

SYNOPSIS

package examples_test

import (
  "bytes"
  "fmt"
  "net/http"
  "time"

  "github.com/lestrrat-go/jwx/v3/jwa"
  "github.com/lestrrat-go/jwx/v3/jwe"
  "github.com/lestrrat-go/jwx/v3/jwk"
  "github.com/lestrrat-go/jwx/v3/jws"
  "github.com/lestrrat-go/jwx/v3/jwt"
)

func Example() {
  // Parse, serialize, slice and dice JWKs!
  privkey, err := jwk.ParseKey(jsonRSAPrivateKey)
  if err != nil {
    fmt.Printf("failed to parse JWK: %s\n", err)
    return
  }

  pubkey, err := jwk.PublicKeyOf(privkey)
  if err != nil {
    fmt.Printf("failed to get public key: %s\n", err)
    return
  }

  // Work with JWTs!
  {
    // Build a JWT!
    tok, err := jwt.NewBuilder().
      Issuer(`github.com/lestrrat-go/jwx`).
      IssuedAt(time.Now()).
      Build()
    if err != nil {
      fmt.Printf("failed to build token: %s\n", err)
      return
    }

    // Sign a JWT!
    signed, err := jwt.Sign(tok, jwt.WithKey(jwa.RS256(), privkey))
    if err != nil {
      fmt.Printf("failed to sign token: %s\n", err)
      return
    }

    // Verify a JWT!
    {
      verifiedToken, err := jwt.Parse(signed, jwt.WithKey(jwa.RS256(), pubkey))
      if err != nil {
        fmt.Printf("failed to verify JWS: %s\n", err)
        return
      }
      _ = verifiedToken
    }

    // Work with *http.Request!
    {
      req, err := http.NewRequest(http.MethodGet, `https://github.com/lestrrat-go/jwx`, nil)
      req.Header.Set(`Authorization`, fmt.Sprintf(`Bearer %s`, signed))

      verifiedToken, err := jwt.ParseRequest(req, jwt.WithKey(jwa.RS256(), pubkey))
      if err != nil {
        fmt.Printf("failed to verify token from HTTP request: %s\n", err)
        return
      }
      _ = verifiedToken
    }
  }

  // Encrypt and Decrypt arbitrary payload with JWE!
  {
    encrypted, err := jwe.Encrypt(payloadLoremIpsum, jwe.WithKey(jwa.RSA_OAEP(), jwkRSAPublicKey))
    if err != nil {
      fmt.Printf("failed to encrypt payload: %s\n", err)
      return
    }

    decrypted, err := jwe.Decrypt(encrypted, jwe.WithKey(jwa.RSA_OAEP(), jwkRSAPrivateKey))
    if err != nil {
      fmt.Printf("failed to decrypt payload: %s\n", err)
      return
    }

    if !bytes.Equal(decrypted, payloadLoremIpsum) {
      fmt.Printf("verified payload did not match\n")
      return
    }
  }

  // Sign and Verify arbitrary payload with JWS!
  {
    signed, err := jws.Sign(payloadLoremIpsum, jws.WithKey(jwa.RS256(), jwkRSAPrivateKey))
    if err != nil {
      fmt.Printf("failed to sign payload: %s\n", err)
      return
    }

    verified, err := jws.Verify(signed, jws.WithKey(jwa.RS256(), jwkRSAPublicKey))
    if err != nil {
      fmt.Printf("failed to verify payload: %s\n", err)
      return
    }

    if !bytes.Equal(verified, payloadLoremIpsum) {
      fmt.Printf("verified payload did not match\n")
      return
    }
  }
  // OUTPUT:
}

source: examples/jwx_readme_example_test.go

How-to Documentation

• API documentation
• How-to style documentation
• Runnable Examples

Description

This Go module implements JWA, JWE, JWK, JWS, and JWT. Please see the following table for the list of available packages:

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

History

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/v3. This library is extensible, customizable, and hopefully well organized to the point that it is easy for you to slice and dice it.

Why would I use this library?

There are several other major Go modules that handle JWT and related data formats, so why should you use this library?

From a purely functional perspective, the only major difference is this: Whereas most other projects only deal with what they seem necessary to handle JWTs, this module handles the entire spectrum of JWS, JWE, JWK, and JWT.

That is, if you need to not only parse JWTs, but also to control JWKs, or if you need to handle payloads that are NOT JWTs, you should probably consider using this module. You should also note that JWT is built on top of those other technologies. You simply cannot have a complete JWT package without implementing the entirety of JWS/JWE/JWK, which this library does.

Next, from an implementation perspective, this module differs significantly from others in that it tries very hard to expose only the APIs, and not the internal data. For example, individual JWT claims are not accessible through struct field lookups. You need to use one of the getter methods.

This is because this library takes the stance that the end user is fully capable and even willing to shoot themselves on the foot when presented with a lax API. By making sure that users do not have access to open structs, we can protect users from doing silly things like creating incomplete structs, or access the structs concurrently without any protection. This structure also allows us to put extra smarts in the structs, such as doing the right thing when you want to parse / write custom fields (this module does not require the user to specify alternate structs to parse objects with custom fields)

In the end I think it comes down to your usage pattern, and priorities. Some general guidelines that come to mind are:

• If you want a single library to handle everything JWx, such as using JWE, JWK, JWS, handling auto-refreshing JWKs, use this module.
• If you want to honor all possible custom fields transparently, use this module.
• If you want a standardized clean API, use this module.

Otherwise, feel free to choose something else.

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 exercise the changes you made.

If you are editing auto-generated files (those files with the _gen.go suffix, please make sure that you do the following:

1. Edit the generator, not the generated files (e.g. internal/cmd/genreadfile/main.go)
2. Run make generate (or go generate) to generate the new code
3. Commit both the generator and the generated files

Discussions / Usage

Please try discussions first.

Related Modules

• github.com/lestrrat-go/echo-middleware-jwx - Sample Echo middleware
• github.com/jwx-go/crypto-signer/gcp - GCP KMS wrapper that implements crypto.Signer
• github.com/jwx-go/crypto-signer/aws - AWS KMS wrapper that implements crypto.Signer

Credits

• Initial work on this library was generously sponsored by HDE Inc (https://www.hde.co.jp)
• Lots of code, especially JWE was initially taken from go-jose library (https://github.com/square/go-jose)
• Lots of individual contributors have helped this project over the years. Thank each and everyone of you very much.

Quid pro quo

If you use this software to build products in a for-profit organization, we ask you to consider contributing back to FOSS in the following manner:

• For every 100 employees (direct hires) of your organization, please consider contributing minimum of $1 every year to either this project, or another FOSS projects that this project uses. For example, for 100 employees, we ask you contribute $100 yearly; for 10,000 employees, we ask you contribute $10,000 yearly.
• If possible, please make this information public. You do not need to disclose the amount you are contributing, but please make the information that you are contributing to particular FOSS projects public. For this project, please consider writing your name on the Wiki

This is NOT a licensing term: you are still free to use this software according to the license it comes with. This clause is only a plea for people to acknowledge the work from FOSS developers whose work you rely on each and everyday.

Documentation

Overview

Package jwx contains tools that deal with the various JWx (JOSE) technologies such as JWT, JWS, JWE, etc in Go.

JWS (https://tools.ietf.org/html/rfc7515)
JWE (https://tools.ietf.org/html/rfc7516)
JWK (https://tools.ietf.org/html/rfc7517)
JWA (https://tools.ietf.org/html/rfc7518)
JWT (https://tools.ietf.org/html/rfc7519)

Examples are stored in a separate Go module (to avoid adding dependencies to this module), and thus does not appear in the online documentation for this module. You can find the examples in Github at https://github.com/lestrrat-go/jwx/tree/v3/examples

You can find more high level documentation at Github (https://github.com/lestrrat-go/jwx/tree/v2)

FAQ style documentation can be found in the repository (https://github.com/lestrrat-go/jwx/tree/develop/v3/docs)

Index

• func DecoderSettings(options ...JSONOption)
• type FormatKind
  • func GuessFormat(payload []byte) FormatKind
  • func (i FormatKind) String() string
• type JSONOption
  • func WithUseNumber(b bool) JSONOption
• type Option

Functions

func DecoderSettings

func DecoderSettings(options ...JSONOption)

DecoderSettings gives you a access to configure the "encoding/json".Decoder used to decode JSON objects within the jwx framework.

All options accepted here have process-global effect and are intended to be applied exactly once at program startup, before any goroutine begins parsing JWx payloads. See the godoc on individual JSONOption constructors (e.g. WithUseNumber) for the concurrency contract of each setting.

Types

type FormatKind

type FormatKind int

const (
	// InvalidFormat is returned when the format of the incoming buffer
	// has been deemed conclusively invalid
	InvalidFormat FormatKind = iota
	// UnknownFormat is returned when GuessFormat was not able to conclusively
	// determine the format of the
	UnknownFormat
	JWE
	JWS
	JWK
	JWKS
	JWT
)

These constants describe the result from guessing the format of the incoming buffer.

func GuessFormat

func GuessFormat(payload []byte) FormatKind

GuessFormat is used to guess the format the given payload is in using heuristics. See the type FormatKind for a full list of possible types.

This may be useful in determining your next action when you may encounter a payload that could either be a JWE, JWS, or a plain JWT.

Because JWTs are almost always JWS signed, you may be thrown off if you pass what you think is a JWT payload to this function. If the function is in the "Compact" format, it means it's a JWS signed message, and its payload is the JWT. Therefore this function will return JWS, not JWT.

This function requires an extra parsing of the payload, and therefore may be inefficient if you call it every time before parsing.

func (FormatKind) String

func (i FormatKind) String() string

type JSONOption

type JSONOption interface {
	Option
	// contains filtered or unexported methods
}

func WithUseNumber

func WithUseNumber(b bool) JSONOption

WithUseNumber controls whether the jwx package should unmarshal JSON objects with the "encoding/json".Decoder.UseNumber feature on.

This setting has process-global effect and must be applied once at program startup (typically from func init() or early in main()) before any goroutine begins parsing JWx payloads. The underlying flag is read atomically, so toggling it at runtime is race-free, but any in-flight or subsequent decoders will observe a mix of float64 and json.Number values in concurrently-decoded custom fields — callers that type-assert on those values will break non-deterministically. There is no per-call override.

Default is false.

type Option

type Option = option.Interface