Skip to content

Changes-v2.md

Latest commit

 

History

History
390 lines (282 loc) · 14.5 KB

Changes-v2.md

File metadata and controls

390 lines (282 loc) · 14.5 KB

Incompatible Changes from v1 to v2

These are changes that are incompatible with the v1.x.x version.

  • tl;dr - If you don't feel like reading the details -- but you will read the details, right?
  • Detailed List of Changes - A comprehensive list of changes from v1 to v2

tl;dr

JWT

// most basic
jwt.Parse(serialized, jwt.WithKey(alg, key)) // NOTE: verification and validation are ENABLED by default!
jwt.Sign(token, jwt.WithKey(alg,key))

// with a jwk.Set
jwt.Parse(serialized, jwt.WithKeySet(set))

// UseDefault/InferAlgorithm with JWKS
jwt.Parse(serialized, jwt.WithKeySet(set,
  jws.WithUseDefault(true), jws.WithInferAlgorithm(true))

// Use `jku`
jwt.Parse(serialized, jwt.WithVerifyAuto(...))

// Any other custom key provisioning (using functions in this
// example, but can be anything that fulfills jws.KeyProvider)
jwt.Parse(serialized, jwt.WithKeyProvider(jws.KeyProviderFunc(...)))

JWK

// jwk.New() was confusing. Renamed to fit the actual implementation
key, err := jwk.FromRaw(rawKey)

// Algorithm() now returns jwa.KeyAlgorithm type. `jws.Sign()`
// and other function that receive JWK algorithm names accept
// this new type, so you can use the same key and do the following
// (previosly you needed to type assert)
jws.Sign(payload, jws.WithKey(key.Algorithm(), key))

// If you need the specific type, type assert
key.Algorithm().(jwa.SignatureAlgorithm)

// jwk.AutoRefresh is no more. Use jwk.Cache
cache := jwk.NewCache(ctx, options...)

// Certificate chains are no longer jwk.CertificateChain type, but
// *(github.com/lestrrat-go/jwx/cert).Chain
cc := key.X509CertChain() // this is *cert.Chain now

JWS

// basic
jws.Sign(payload, jws.WithKey(alg, key))
jws.Sign(payload, jws.WithKey(alg, key), jws.WithKey(alg, key), jws.WithJSON(true))
jws.Verify(signed, jws.WithKey(alg, key))

// other ways to pass the key
jws.Sign(payload, jws.WithKeySet(jwks))
jws.Sign(payload, jws.WithKeyProvider(kp))

// retrieve the key that succeeded in verifying
var keyUsed interface{}
jws.Verify(signed, jws.WithKeySet(jwks), jws.WithKeyUsed(&keyUsed))

JWE

// basic
jwe.Encrypt(payload, jwe.WithKey(alg, key)) // other defaults are infered
jwe.Encrypt(payload, jwe.WithKey(alg, key), jwe.WithKey(alg, key), jwe.WithJSON(true))
jwe.Decrypt(encrypted, jwe.WithKey(alg, key))

// other ways to pass the key
jwe.Encrypt(payload, jwe.WithKeySet(jwks))
jwe.Encrypt(payload, jwe.WithKeyProvider(kp))

// retrieve the key that succeeded in decrypting
var keyUsed interface{}
jwe.Verify(signed, jwe.WithKeySet(jwks), jwe.WithKeyUsed(&keyUsed))

Detailed List of Changes

Module

  • Module now requires go 1.16

  • Use of github.com/pkg/errors is no more. If you were relying on bevaior that depends on the errors being an instance of github.com/pkg/errors then you need to change your code

  • File-generation tools have been moved out of internal/ directories. These files pre-dates Go modules, and they were in internal/ in order to avoid being listed in the go doc -- however, now that we can make them separate modules this is no longer necessary.

  • New package cert has been added to handle x5c certificate chains, and to work with certificates

    • cert.Chain to store base64 encoded ASN.1 DER format certificates
    • cert.EncodeBase64 to encode ASN.1 DER format certificate using base64
    • cert.Create to create a base64 encoded ASN.1 DER format certificates
    • cert.Parse to parse base64 encoded ASN.1 DER format certificates

JWE

  • jwe.Compact()'s signature has changed to jwe.Compact(*jwe.Message, ...jwe.CompactOption)

  • jwe.JSON() has been removed. You can generate JSON serialization using jwe.Encrypt(jwe.WitJSON()) or json.Marshal(jwe.Message)

  • (jwe.Message).Decrypt() has been removed. Since formatting of the original serialized message matters (including whitespace), using a parsed object was inherently confusing.

  • jwe.Encrypt() can now generate JWE messages in either compact or JSON forms. By default, the compact form is used. JSON format can be enabled by using the jwe.WithJSON option.

  • jwe.Encrypt() can now accept multiple keys by passing multiple jwe.WithKey() options. This can be used with jwe.WithJSON to create JWE messages with multiple recipients.

  • jwe.DecryptEncryptOption() has been renamed to jwe.EncryptDecryptOption(). This is so that it is more uniform with jws equivalent of jws.SignVerifyOption() where the producer (Sign) comes before the consumer (Verify) in the naming

  • jwe.WithCompact and jwe.WithJSON options have been added to control the serialization format.

  • jwe.Decrypt()'s method signature has been changed to jwt.Decrypt([]byte, ...jwe.DecryptOption) ([]byte, error). These options can be stacked. Therefore, you could configure the verification process to attempt a static key pair, a JWKS, and only try other forms if the first two fails, for example.

    • For static key pair, use jwe.WithKey()
    • For static JWKS, use jwe.WithKeySet() (NOTE: InferAlgorithmFromKey like in jws package is NOT supported)
    • For custom, possibly dynamic key provisioning, use jwe.WithKeyProvider()

  • jwe.Decrypter has been unexported. Users did not need this.

  • jwe.WithKeyProvider() has been added to specify arbitrary code to specify which keys to try.

  • jwe.KeyProvider interface has been added

  • jwe.KeyProviderFunc has been added

  • WithPostParser() has been removed. You can achieve the same effect by using jwe.WithKeyProvider(). Because this was the only consumer for jwe.DecryptCtx, this type has been removed as well.

  • x5c field type has been changed to *cert.Chain instead of []string

  • Method signature for jwe.Parse() has been changed to include options, but options are currently not used

  • jwe.ReadFile now supports the option jwe.WithFS which allows you to read data from arbitrary fs.FS objects

  • jwe.WithKeyUsed has been added to allow users to retrieve the key used for decryption. This is useful in cases you provided multiple keys and you want to know which one was successful

JWK

  • jwk.New() has been renamed to jwk.FromRaw(), which hopefully will make it easier for the users what the input should be.

  • jwk.Set has many interface changes:

    • Changed methods to match jwk.Key and its semantics:
      • Field is now Get() (returns values for arbitrary fields other than keys). Fetching a key is done via Key()
      • Remove() now removes arbitrary fields, not keys. to remove keys, use RemoveKey()
      • Iterate has been added to iterate through all non-key fields.
    • Add is now AddKey(Key) string, and returns an error when the same key is added
    • Get is now Key(int) (Key, bool)
    • Remove is now RemoveKey(Key) error
    • Iterate is now Keys(context.Context) KeyIterator
    • Clear is now Clear() error

  • jwk.CachedSet has been added. You can create a jwk.Set that is backed by jwk.Cache so you can do this:

cache := jkw.NewCache(ctx)
cachedSet := jwk.NewCachedSet(cache, jwksURI)

// cachedSet is always the refreshed, cached version from jwk.Cache
jws.Verify(signed, jws.WithKeySet(cachedSet))

  • jwk.NewRSAPRivateKey(), jwk.NewECDSAPrivateKey(), etc have been removed. There is no longer any way to create concrete types of jwk.Key

  • jwk.Key type no longer supports direct unmarshaling via json.Unmarshal(), because you can no longer instantiate concrete jwk.Key types. You will need to use jwk.ParseKey(). See the documentation for ways to parse JWKs.

  • (jwk.Key).Algorithm() is now of jwk.KeyAlgorithm type. This field used to be string and therefore could not be passed directly to jwt.Sign() jws.Sign(), jwe.Encrypt(), et al. This is no longer the case, and now you can pass it directly. See https://github.com/lestrrat-go/jwx/blob/v2/docs/99-faq.md#why-is-jwkkeyalgorithm-and-jwakeyalgorithm-so-confusing for more details

  • jwk.Fetcher and jwk.FetchFunc has been added. They represent something that can fetch a jwk.Set

  • jwk.CertificateChain has been removed, use *cert.Chain

  • x5c field type has been changed to *cert.Chain instead of []*x509.Certificate

  • jwk.ReadFile now supports the option jwk.WithFS which allows you to read data from arbitrary fs.FS objects

  • Added jwk.PostFetcher, jwk.PostFetchFunc, and jwk.WithPostFetch to allow users to get at the jwk.Set that was fetched in jwk.Cache. This will make it possible for users to supply extra information and edit jwk.Set after it has been fetched and parsed, but before it is cached. You could, for example, modify the alg field so that it's easier to work with when you use it in jws.Verify later.

  • Reworked jwk.AutoRefresh in terms of github.com/lestrrat-go/httprc and renamed it jwk.Cache.

    Major difference between jwk.AutoRefresh and jwk.Cache is that while former used one time.Timer per resource, the latter uses a static timer (based on jwk.WithRefreshWindow() value, default 15 minutes) that periodically refreshes all resources that were due to be refreshed within that time frame.

    This method may cause your updates to happen slightly later, but uses significantly less resources and is less prone to clogging.

  • Reimplemented jwk.Fetch in terms of github.com/lestrrat-go/httprc.

  • Previously jwk.Fetch and jwk.AutoRefresh respected backoff options, but this has been removed. This is to avoid unwanted clogging of the fetch workers which is the default processing mode in github.com/lestrrat-go/httprc.

    If you are using backoffs, you need to control your inputs more carefully so as to not clog your fetch queue, and therefore you should be writing custom code that suits your needs

JWS

  • jws.Sign() can now generate JWS messages in either compact or JSON forms. By default, the compact form is used. JSON format can be enabled by using the jws.WithJSON option.

  • jws.Sign() can now accept multiple keys by passing multiple jws.WithKey() options. This can be used with jws.WithJSON to create JWS messages with multiple signatures.

  • jws.WithCompact and jws.WithJSON options have been added to control the serialization format.

  • jws.Verify()'s method signature has been changed to jwt.Verify([]byte, ...jws.VerifyOption) ([]byte, error). These options can be stacked. Therefore, you could configure the verification process to attempt a static key pair, a JWKS, and only try other forms if the first two fails, for example.

    • For static key pair, use jws.WithKey()
    • For static JWKS, use jws.WithKeySet()
    • For enabling verification using jku, use jws.WithVerifyAuto()
    • For custom, possibly dynamic key provisioning, use jws.WithKeyProvider()

  • jws.WithVerify() has been removed.

  • jws.WithKey() has been added to specify an algorithm + key to verify the payload with.

  • jws.WithKeySet() has been added to specify a JWKS to be used for verification. By default kid AND alg must match between the signature and the key.

    The option can take further suboptions:

jws.Parse(serialized,
  jws.WithKeySet(set,
    // by default `kid` is required. set false to disable.
    jws.WithRequireKid(false),
    // optionally skip matching kid if there's exactly one key in set
    jws.WithUseDefault(true),
    // infer algorithm name from key type
    jws.WithInferAlgorithm(true),
  ),
)

  • jws.VerifuAuto has been removed in favor of using jws.WithVerifyAuto option with jws.Verify()

  • jws.WithVerifyAuto has been added to enable verification using jku.

    The first argument must be a jwk.Fetcher object, but can be set to nil to use the default implementation which is jwk.Fetch

    The rest of the arguments are treated as options passed to the (jwk.Fetcher).Fetch() function.

  • Remove jws.WithPayloadSigner(). This should be completely repleceable using jws.WithKey()

  • jws.WithKeyProvider() has been added to specify arbitrary code to specify which keys to try.

  • jws.KeyProvider interface has been added

  • jws.KeyProviderFunc has been added

  • jws.WithKeyUsed has been added to allow users to retrieve the key used for verification. This is useful in cases you provided multiple keys and you want to know which one was successful

  • x5c field type has been changed to *cert.Chain instead of []string

  • jws.ReadFile now supports the option jws.WithFS which allows you to read data from arbitrary fs.FS objects

JWT

  • jwt.Parse now verifies the signature and validates the token by default. You must disable it explicitly using jwt.WithValidate(false) and/or jwt.WithVerify(false) if you only want to parse the JWT message.

    If you don't want either, a convenience function jwt.ParseInsecure has been added.

  • jwt.Parse can only parse raw JWT (JSON) or JWS (JSON or Compact). It no longer accepts JWE messages.

  • jwt.WithDecrypt has been removed

  • jwt.WithJweHeaders has been removed

  • jwt.WithVerify() has been renamed to jwt.WithKey(). The option can be used for signing, encryption, and parsing.

  • jwt.Validator has been changed to return jwt.ValidationError. If you provide a custom validator, you should wrap the error with jwt.NewValidationError()

  • jwt.UseDefault() has been removed. You should use jws.WithUseDefault() as a suboption in the jwt.WithKeySet() option.

jwt.Parse(serialized, jwt.WithKeySet(set, jws.WithUseDefault(true)))
  • jwt.InferAlgorithmFromKey() has been removed. You should use jws.WithInferAlgorithmFromKey() as a suboption in the jwt.WithKeySet() option.
jwt.Parse(serialized, jwt.WithKeySet(set, jws.WithInferAlgorithmFromKey(true)))
  • jwt.WithKeySetProvider has been removed. Use jwt.WithKeyProvider() instead. If jwt.WithKeyProvider seems a bit complicated, use a combination of JWS parse, no-verify/validate JWT parse, and an extra JWS verify:
msg, _ := jws.Parse(signed)
token, _ := jwt.Parse(msg.Payload(), jwt.WithVerify(false), jwt.WithValidate(false))
// Get information out of token, for example, `iss`
switch token.Issuer() {
case ...:
  jws.Verify(signed, jwt.WithKey(...))
}

  • jwt.WithHeaders and jwt.WithJwsHeaders have been removed. You should be able to use the new jwt.WithKey option to pass headers

  • jwt.WithSignOption and jwt.WithEncryptOption have been added as escape hatches for options that are declared in jws and jwe packages but not in jwt

  • jwt.ReadFile now supports the option jwt.WithFS which allows you to read data from arbitrary fs.FS objects

  • jwt.Sign() has been changed so that it works more like the new jws.Sign()