JWX

https://pkg.go.dev/github.com/lestrrat-go/jwx/v2
Admin
JWX is a comprehensive Go module that implements JWA, JWE, JWK, JWS, and JWT with complete JOSE...
Tokens:126,654
Snippets:1,508
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example of retrieving keys from KeySink

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Shows how to retrieve all keys that have been provided to the KeySink for signature verification.

```go
keys := sink.Keys()
for key in keys {
  if givenSignature == makeSignature(key, payload, ...)) {
    return OK
  }
}
```

--------------------------------

### Example of Serializing a Token with Sign and Encrypt

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

This example demonstrates how to use the jwt.NewSerializer() to marshal a token into JSON, then apply JWS signing and JWE encryption in sequence.

```go
serialized, err := jwt.NewSerializer().
   Sign(jwa.RS256, key).
   Encrypt(jwa.RSA_OAEP, key.PublicKey).
   Serialize(token)
```

--------------------------------

### Example of RegisterCustomField Usage

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Demonstrates registering a custom field 'x-birthday' to be decoded as a time.Time object.

```go
jwe.RegisterCustomField(`x-birthday`, timeT)


hdr.Get(`x-birthday`)
```

--------------------------------

### Get All Key Types

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwa

Retrieves a list of all available KeyType values supported by the library.

```go
func KeyTypes() []KeyType
```

--------------------------------

### KeyProvider Pseudocode Example: Filtering

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Illustrates the pseudocode for filtering KeyProviders from an options list before processing.

```pseudocode
keyProviders := filterKeyProviders(options)
```

--------------------------------

### Example of Signing a Token using Serializer

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

This shows an equivalent way to sign a token using the serializer, similar to the jwt.Sign() function.

```go
serialized, err := jwt.NewSerializer().
   Sign(...args...). 
   Serialize(token)
```

--------------------------------

### Get All Key Encryption Algorithms

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwa

Retrieves a list of all available KeyEncryptionAlgorithm values supported by the library.

```go
func KeyEncryptionAlgorithms() []KeyEncryptionAlgorithm
```

--------------------------------

### jwx README Example

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2

Demonstrates parsing JWKs, working with JWTs (building, signing, verifying, parsing from requests), and performing JWE encryption/decryption and JWS signing/verification with arbitrary payloads. Requires JWK keys and payload data to be defined elsewhere.

```go
package examples_test

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

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

func Example_jwx_readme() {
  // 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:
}

```

--------------------------------

### KeyProvider Pseudocode Example: Fetching Keys for Recipients

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Shows pseudocode for iterating through recipients and KeyProviders to fetch necessary keys for decryption.

```pseudocode
for r in msg.Recipients {
  for kp in keyProviders {
    kp.FetchKeys(ctx, sink, r, msg)
    ...
  }
}
```

--------------------------------

### Example of jwx tool usage for parsing and verification

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Demonstrates a command-line workflow using the 'jwx' tool to parse a JWS message and then verify it with a key.

```bash
jwx jws parse message.jws | jwx jws verify --key somekey.jwk --stdin
```

--------------------------------

### Get Available Signature Algorithms

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwa

Retrieves a list of all currently supported SignatureAlgorithm values. This function is useful for introspection.

```go
func SignatureAlgorithms() []SignatureAlgorithm
```

--------------------------------

### Get Signature Algorithms for Key

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Retrieves possible signature algorithms for a given key, primarily for verification purposes.

```go
func AlgorithmsForKey(key interface{}) ([]jwa.SignatureAlgorithm, error)
```

--------------------------------

### Serializer Usage Example

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Demonstrates how to use the Serializer to marshal a token into JSON, then apply JWS and JWE signing and encryption.

```APIDOC
## Serializer Usage Example

### Description
This example shows how to create a JWT serializer, apply signing and encryption steps, and then serialize a token.

### Method
```go
serialized, err := jwt.NewSerializer().
   Sign(jwa.RS256, key).
   Encrypt(jwa.RSA_OAEP, key.PublicKey).
   Serialize(token)
```

### Parameters
- `token` (Token): The JWT token to serialize.
- `jwa.RS256` (jwa.KeyAlgorithm): The algorithm to use for signing.
- `key` (interface{}): The key to use for signing.
- `jwa.RSA_OAEP` (jwa.KeyAlgorithm): The algorithm to use for encryption.
- `key.PublicKey` (interface{}): The public key to use for encryption.

### Response
- `serialized` ([]byte): The serialized JWT.
- `err` (error): An error if the serialization fails.
```

--------------------------------

### KeyProvider Pseudocode Example

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Pseudocode illustrating how KeyProviders are filtered and used in the verification process for each signature in a JWS message.

```pseudocode
keyProviders := filterKeyProviders(options)

for sig in msg.Signatures {
  for kp in keyProviders {
    kp.FetchKeys(ctx, sink, sig, msg)
    ...
  }
}
```

--------------------------------

### Example of JSON header serialization difference

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Illustrates the difference in JSON serialization for protected headers between the original message and Go's marshaling, potentially causing verification issues.

```json
{"typ":"JWT",
  "alg":"HS256"}
```

--------------------------------

### Implement JWT Clock Interface

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Defines the Now() method for getting the current time, used by the JWT library.

```go
type Clock interface {
	Now() time.Time
}
```

--------------------------------

### Get a new bytes.Buffer object

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/pool

Acquires a reusable bytes.Buffer object from the pool. Use this to avoid repeated allocations.

```go
func GetBytesBuffer() *bytes.Buffer
```

--------------------------------

### StringList Get Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/internal/types

The Get method for StringList, returning the underlying slice of strings.

```go
func (l StringList) Get() []string
```

--------------------------------

### NumericDate Get Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/internal/types

The Get method for NumericDate, returning the underlying time.Time value.

```go
func (n *NumericDate) Get() time.Time
```

--------------------------------

### Create New Registry

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/json

Creates and returns a new instance of Registry.

```go
func NewRegistry() *Registry
```

--------------------------------

### Cache Get Method Signature

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Signature for the Get method of the Cache type. It retrieves a JWK set from the cache using its URL.

```go
func (c *Cache) Get(ctx context.Context, u string) (Set, error)
```

--------------------------------

### Get Available Algorithms

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/jose

Retrieves the available algorithms as an AlgorithmSet. This function requires context and a test object, and returns the set and an error. Added in v2.0.9.

```go
func Algorithms(ctx context.Context, t *testing.T) (*AlgorithmSet, error)
```

--------------------------------

### KeyProviderFunc FetchKeys Method Implementation

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Shows the FetchKeys method implementation for the KeyProviderFunc type.

```go
func (kp KeyProviderFunc) FetchKeys(ctx context.Context, sink KeySink, r Recipient, msg *Message) error
```

--------------------------------

### Compression Algorithms

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwa

Defines CompressionAlgorithm type with constants for DEFLATE and No Compression. Provides functions to get all supported algorithms and to accept external values.

```APIDOC
## CompressionAlgorithm

### Description
Represents compression algorithms as defined in RFC 7518, Section 7.3.

### Constants
- `Deflate`: Represents DEFLATE (RFC 1951) compression.
- `NoCompress`: Represents no compression.

### Functions
#### `CompressionAlgorithms()`
- **Description**: Returns a slice of all available `CompressionAlgorithm` values.
- **Signature**: `func CompressionAlgorithms() []CompressionAlgorithm`

#### `(*CompressionAlgorithm) Accept(value interface{}) error`
- **Description**: Used for converting values from external sources (like JSON payloads) into a `CompressionAlgorithm`.
- **Signature**: `func (v *CompressionAlgorithm) Accept(value interface{}) error`

#### `(CompressionAlgorithm) String() string`
- **Description**: Returns the string representation of a `CompressionAlgorithm`.
- **Signature**: `func (v CompressionAlgorithm) String() string`
```

--------------------------------

### CachedSet: Get Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Returns the value of non-Key field stored in the jwk.Set.

```go
func (cs *CachedSet) Get(name string) (interface{}, bool)
```

--------------------------------

### Struct vs Interface for Token Initialization

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Illustrates the difference in handling token initialization and custom claims between a hypothetical struct-based token and the interface-based approach, highlighting the issue of semantically equivalent but distinct zero values.

```go
// assume jwt.Token was s struct, not an interface
token1 := jwt.Token{ privateClaims: make(map[string]interface{}) }
token2 := jwt.Token{ privateClaims: nil }

```

--------------------------------

### Get JSON Engine Name

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/json

Returns the name of the JSON engine being used.

```go
func Engine() string
```

--------------------------------

### Create and Sign a JWT

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Demonstrates creating a new JWT, setting various claims (subject, audience, issued at, private claims), marshaling it to JSON, and then signing it using both a raw RSA private key and a JWK key.

```go
const aLongLongTimeAgo = 233431200

t := jwt.New()
t.Set(jwt.SubjectKey, `https://github.com/lestrrat-go/jwx/v2/jwt`)
t.Set(jwt.AudienceKey, `Golang Users`)
t.Set(jwt.IssuedAtKey, time.Unix(aLongLongTimeAgo, 0))
t.Set(`privateClaimKey`, `Hello, World!`)

buf, err := json.MarshalIndent(t, "", "  ")
if err != nil {
  fmt.Printf("failed to generate JSON: %s\n", err)
  return
}

fmt.Printf("%s\n", buf)
fmt.Printf("aud -> '%s'\n", t.Audience())
fmt.Printf("iat -> '%s'\n", t.IssuedAt().Format(time.RFC3339))
if v, ok := t.Get(`privateClaimKey`); ok {
  fmt.Printf("privateClaimKey -> '%s'\n", v)
}
fmt.Printf("sub -> '%s'\n", t.Subject())

key, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
  log.Printf("failed to generate private key: %s", err)
  return
}

{
  // Signing a token (using raw rsa.PrivateKey)
  signed, err := jwt.Sign(t, jwt.WithKey(jwa.RS256, key))
  if err != nil {
    log.Printf("failed to sign token: %s", err)
    return
  }
  _ = signed
}

{
  // Signing a token (using JWK)
  jwkKey, err := jwk.New(key)
  if err != nil {
    log.Printf("failed to create JWK key: %s", err)
    return
  }

  signed, err := jwt.Sign(t, jwt.WithKey(jwa.RS256, jwkKey))
  if err != nil {
    log.Printf("failed to sign token: %s", err)
    return
  }
  _ = signed
}

```

--------------------------------

### Get Length of Certificate Chain

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/cert

Returns the number of certificates currently stored in the Chain.

```go
func (cc *Chain) Len() int
```

--------------------------------

### Handle OpenID Claims with JWT

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Demonstrates creating an OpenID specific token, setting OpenID claims including an address, marshaling it to JSON, and then parsing it back using `jwt.WithToken(openid.New())` to ensure it's treated as an OpenID token.

```go
const aLongLongTimeAgo = 233431200

t := openid.New()
t.Set(jwt.SubjectKey, `https://github.com/lestrrat-go/jwx/v2/jwt`)
t.Set(jwt.AudienceKey, `Golang Users`)
t.Set(jwt.IssuedAtKey, time.Unix(aLongLongTimeAgo, 0))
t.Set(`privateClaimKey`, `Hello, World!`)

addr := openid.NewAddress()
addr.Set(openid.AddressPostalCodeKey, `105-0011`)
addr.Set(openid.AddressCountryKey, `日本`)
addr.Set(openid.AddressRegionKey, `東京都`)
addr.Set(openid.AddressLocalityKey, `港区`)
addr.Set(openid.AddressStreetAddressKey, `芝公園 4-2-8`)
t.Set(openid.AddressKey, addr)

buf, err := json.MarshalIndent(t, "", "  ")
if err != nil {
  fmt.Printf("failed to generate JSON: %s\n", err)
  return
}
fmt.Printf("%s\n", buf)

t2, err := jwt.Parse(buf, jwt.WithToken(openid.New()))
if err != nil {
  fmt.Printf("failed to parse JSON: %s\n", err)
  return
}
if _, ok := t2.(openid.Token); !ok {
  fmt.Printf("using jwt.WithToken(openid.New()) creates an openid.Token instance")
  return
}

```

--------------------------------

### Using WithKey for Signing or Parsing

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Illustrates the usage of WithKey, which can be used for jwt.Sign, jwt.Parse, and jwt.Serializer methods. It highlights the importance of matching suboptions to the operation.

```go
jwt.Sign(token, jwt.WithKey(alg, key, jweOptions...))
```

--------------------------------

### Get Tag from JWE Message

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Retrieves the authentication tag from a JWE Message. The tag is a byte slice.

```go
func (m *Message) Tag() []byte
```

--------------------------------

### Get Recipients from JWE Message

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Retrieves the recipients associated with a JWE Message. Each recipient is of type Recipient.

```go
func (m *Message) Recipients() []Recipient
```

--------------------------------

### WithKeyProvider Option

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Specifies a KeyProvider for obtaining keys during verification. This allows for dynamic key retrieval.

```go
func WithKeyProvider(v KeyProvider) VerifyOption
```

--------------------------------

### AddressClaim Get Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/openid

Retrieves a value from the AddressClaim by key, returning the value and a boolean indicating its presence.

```go
func (t *AddressClaim) Get(s string) (interface{}, bool)
```

--------------------------------

### Create New Decode Context

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/json

Creates a new DecodeCtx with the provided Registry.

```go
func NewDecodeCtx(r *Registry) DecodeCtx
```

--------------------------------

### Get Private Key Seed

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/x25519

Returns the private key seed, useful for RFC 7748 interoperability.

```go
func (priv PrivateKey) Seed() []byte
```

--------------------------------

### Get Executable Path

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/jose

Retrieves the executable path for the JOSE tool. This function returns the path as a string.

```go
func ExecutablePath() string
```

--------------------------------

### Using Pointers for Claim Initialization State

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Explains the internal use of pointers to differentiate between an uninitialized claim (nil pointer) and a claim initialized to an empty value (pointer to an empty string), and why this is avoided in the public API.

```go
type stdToken struct {
  ....
  issuer *string // if nil, uninitialized. if &(""), initialized to empty
}

```

--------------------------------

### AvailableAlgorithms

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/ecutil

AvailableAlgorithms returns a list of all supported elliptic curve algorithms.

```APIDOC
## AvailableAlgorithms

### Description
AvailableAlgorithms returns a list of all supported elliptic curve algorithms.

### Signature
```go
func AvailableAlgorithms() []jwa.EllipticCurveAlgorithm
```
```

--------------------------------

### Preferred API for Setting Token Claims

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Demonstrates the preferred method of setting token claims using a `Set` function, which abstracts away the internal storage mechanism (like pointers) and provides a cleaner API for users.

```go
token.Issuer = &issuer // want to avoid this

token.Set(jwt.IssuerKey, "foobar") // so this is what we picked

```

--------------------------------

### Get Unprotected Headers from JWE Message

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Retrieves the unprotected headers from a JWE Message. Headers are of type Headers.

```go
func (m *Message) UnprotectedHeaders() Headers
```

--------------------------------

### Get Protected Headers from JWE Message

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Retrieves the protected headers from a JWE Message. Headers are of type Headers.

```go
func (m *Message) ProtectedHeaders() Headers
```

--------------------------------

### Fetch Option: WithHTTPClient

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Allows users to specify the "net/http".Client object that is used when fetching jwk.Set objects.

```go
func WithHTTPClient(v HTTPClient) FetchOption
```

--------------------------------

### Create X.509 Certificate

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/cert

Wrapper around x509.CreateCertificate that additionally encodes the certificate in base64 for easy inclusion in 'x5c' fields.

```go
func Create(rand io.Reader, template, parent *x509.Certificate, pub, priv interface{}) ([]byte, error)
```

--------------------------------

### Get X25519 Key Size

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe/internal/keygen

The Size method returns the key size in bytes that the X25519 generator will produce.

```go
func (g X25519) Size() int
```

--------------------------------

### Create Temporary File

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/jwxtest

Creates a temporary file in the specified directory with the given template. Returns the file handle, a cleanup function, and an error.

```go
func CreateTempFile(dir, template string) (*os.File, func(), error)
```

--------------------------------

### Get Random Key Size

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe/internal/keygen

The Size method returns the number of bytes that the Random generator is configured to produce.

```go
func (g Random) Size() int
```

--------------------------------

### FetchFunc: Fetch Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Fetches a JWK set from a given URL.

```go
func (f FetchFunc) Fetch(ctx context.Context, u string, options ...FetchOption) (Set, error)
```

--------------------------------

### Create ReadFileOption with File System

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Creates a ReadFileOption that specifies the source fs.FS object for reading files. This option is passed to jwe.ReadFile.

```go
func WithFS(v fs.FS) ReadFileOption
```

--------------------------------

### Get Ecdhes Key Size

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe/internal/keygen

The Size method returns the key size in bytes that the Ecdhes generator will produce.

```go
func (g Ecdhes) Size() int
```

--------------------------------

### Get Public Key from Private Key

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/x25519

Returns the corresponding X25519 public key for a given private key.

```go
func (priv PrivateKey) Public() crypto.PublicKey
```

--------------------------------

### Auto-Refresh JWKS with jwk.Cache

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Demonstrates how to use jwk.Cache to automatically refresh a JWKS from a given URL. It shows how to register a JWKS with a minimum refresh interval and how to retrieve keys from the cache within a long-running process.

```go
package examples_test

import (
  "context"
  "fmt"
  "time"

  "github.com/lestrrat-go/jwx/v2/jwk"
)

func Example_jwk_cache() {
  ctx, cancel := context.WithCancel(context.Background())
  defer cancel()

  const googleCerts = `https://www.googleapis.com/oauth2/v3/certs`

  // First, set up the `jwk.Cache` object. You need to pass it a
  // `context.Context` object to control the lifecycle of the background fetching goroutine.
  //
  // Note that by default refreshes only happen very 15 minutes at the
  // earliest. If you need to control this, use `jwk.WithRefreshWindow()`
  c := jwk.NewCache(ctx)

  // Tell *jwk.Cache that we only want to refresh this JWKS
  // when it needs to (based on Cache-Control or Expires header from
  // the HTTP response). If the calculated minimum refresh interval is less
  // than 15 minutes, don't go refreshing any earlier than 15 minutes.
  c.Register(googleCerts, jwk.WithMinRefreshInterval(15*time.Minute))

  // Refresh the JWKS once before getting into the main loop.
  // This allows you to check if the JWKS is available before we start
  // a long-running program
  _, err := c.Refresh(ctx, googleCerts)
  if err != nil {
    fmt.Printf("failed to refresh google JWKS: %s\n", err)
    return
  }

  // Pretend that this is your program's main loop
MAIN:
  for {
    select {
    case <-ctx.Done():
      break MAIN
    default:
    }
    keyset, err := c.Get(ctx, googleCerts)
    if err != nil {
      fmt.Printf("failed to fetch google JWKS: %s\n", err)
      return
    }
    _ = keyset
    // The returned `keyset` will always be "reasonably" new.
    //
    // By "reasonably" we mean that we cannot guarantee that the keys will be refreshed
    // immediately after it has been rotated in the remote source. But it should be close\n    // enough, and should you need to forcefully refresh the token using the `(jwk.Cache).Refresh()` method.
    //
    // If refetching the keyset fails, a cached version will be returned from the previous successful
    // fetch upon calling `(jwk.Cache).Fetch()`.

    // Do interesting stuff with the keyset... but here, we just
    // sleep for a bit
    time.Sleep(time.Second)

    // Because we're a dummy program, we just cancel the loop now.
    // If this were a real program, you presumably loop forever
    cancel()
  }
  // OUTPUT:
}

```

--------------------------------

### KDF Type and Functions

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe/internal/concatkdf

Details on the KDF type, how to create a new KDF instance, and how to read from it.

```APIDOC
## type KDF

```
type KDF struct {
	// contains filtered or unexported fields
}
```

### func New

```go
func New(hash crypto.Hash, alg, Z, apu, apv, pubinfo, privinfo []byte) *KDF
```

#### Description
Creates a new KDF instance.

#### Parameters
* `hash` (crypto.Hash) - The hash algorithm to use.
* `alg` ([]byte) - The algorithm identifier.
* `Z` ([]byte) - The shared secret.
* `apu` ([]byte) - Application-specific information for the sender.
* `apv` ([]byte) - Application-specific information for the receiver.
* `pubinfo` ([]byte) - Public information.
* `privinfo` ([]byte) - Private information.

#### Returns
* `*KDF` - A pointer to the newly created KDF instance.

### func (*KDF) Read

```go
func (k *KDF) Read(out []byte) (int, error)
```

#### Description
Reads derived key material into the provided byte slice.

#### Parameters
* `out` ([]byte) - The byte slice to fill with derived key material.

#### Returns
* `int` - The number of bytes read.
* `error` - An error if the read operation fails.
```

--------------------------------

### Get a new big.Int object

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/pool

Acquires a reusable big.Int object from the pool. Use this to avoid repeated allocations.

```go
func GetBigInt() *big.Int
```

--------------------------------

### VerifierFactoryFn Create Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Implements the Create method for VerifierFactoryFn, returning a new Verifier.

```go
func (fn VerifierFactoryFn) Create() (Verifier, error)
```

--------------------------------

### NewMessage

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Creates a new, empty JWS `Message` object. This is the starting point for constructing a JWS message programmatically.

```APIDOC
## func NewMessage() *Message

### Description
Creates a new, empty JWS `Message` object. This is the starting point for constructing a JWS message programmatically.

### Returns
- `*Message`: A pointer to a new `Message` struct.
```

--------------------------------

### NewBuilder Function

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/openid

Creates and returns a new instance of the Builder.

```go
func NewBuilder() *Builder
```

--------------------------------

### Get Validation Context Clock

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Retrieves the Clock object from the current validation context. This is always available during token validation.

```go
func ValidationCtxClock(ctx context.Context) Clock
```

--------------------------------

### Get Initialization Vector from JWE Message

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Retrieves the Initialization Vector (IV) from a JWE Message. The IV is a byte slice.

```go
func (m *Message) InitializationVector() []byte
```

--------------------------------

### TokenOptionSet Enable Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Enables a specific option in the TokenOptionSet.

```go
func (o *TokenOptionSet) Enable(flag TokenOption)
```

--------------------------------

### WithContext Option

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Sets the context for verification operations. Useful for cancellation and deadlines.

```go
func WithContext(v context.Context) VerifyOption
```

--------------------------------

### NewRegistry

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/json

Creates a new Registry.

```APIDOC
## NewRegistry

### Description
Creates a new Registry.

### Signature
```go
func NewRegistry() *Registry
```
```

--------------------------------

### SignerFactoryFn Create Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Implements the Create method for SignerFactoryFn, returning a new Signer.

```go
func (fn SignerFactoryFn) Create() (Signer, error)
```

--------------------------------

### AddressClaim Region Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/openid

Retrieves the region value from the AddressClaim. Returns the zero value if the value does not exist or cannot be retrieved. Use Get for differentiation.

```go
func (t AddressClaim) Region() string
```

--------------------------------

### AddressClaim Locality Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/openid

Retrieves the locality value from the AddressClaim. Returns the zero value if the value does not exist or cannot be retrieved. Use Get for differentiation.

```go
func (t AddressClaim) Locality() string
```

--------------------------------

### Specify KeyProvider for decryption

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Use WithKeyProvider to supply a KeyProvider for decryption operations.

```go
func WithKeyProvider(v KeyProvider) DecryptOption
```

--------------------------------

### AddressClaim Country Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/openid

Retrieves the country value from the AddressClaim. Returns the zero value if the value does not exist or cannot be retrieved. Use Get for differentiation.

```go
func (t AddressClaim) Country() string
```

--------------------------------

### Get Certificate from Chain by Index

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/cert

Retrieves the n-th ASN.1 DER + base64 encoded certificate from the chain. Returns false if the index is out of range.

```go
func (cc *Chain) Get(index int) ([]byte, bool)
```

--------------------------------

### New KDF Function

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe/internal/concatkdf

Constructor function for creating a new KDF instance. It requires the hash algorithm, algorithm identifier, and various byte slices for keying material and information.

```go
func New(hash crypto.Hash, alg, Z, apu, apv, pubinfo, privinfo []byte) *KDF
```

--------------------------------

### AddressClaim StreetAddress Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/openid

Retrieves the street address value from the AddressClaim. Returns the zero value if the value does not exist or cannot be retrieved. Use Get for differentiation.

```go
func (t AddressClaim) StreetAddress() string
```

--------------------------------

### WithKey Function

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Specifies the key algorithm and key for signing or verification. Accepts optional suboptions.

```go
func WithKey(alg jwa.KeyAlgorithm, key interface{}, options ...WithKeySuboption) SignVerifyOption
```

--------------------------------

### AddressClaim PostalCode Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/openid

Retrieves the postal code value from the AddressClaim. Returns the zero value if the value does not exist or cannot be retrieved. Use Get for differentiation.

```go
func (t AddressClaim) PostalCode() string
```

--------------------------------

### AddressClaim Formatted Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/openid

Retrieves the formatted address value from the AddressClaim. Returns the zero value if the value does not exist or cannot be retrieved. Use Get for differentiation.

```go
func (t AddressClaim) Formatted() string
```

--------------------------------

### Register and Refresh JWKS

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Demonstrates how to register a URL with the cache and then immediately refresh it to validate the JWKS. This is useful for ensuring a URL is valid before proceeding.

```go
import (
	"context"
	"log"

	"github.com/lestrrat-go/jwx/v2/jwk"
)

func main() {
	ctx := context.Background()

	cache := jwk.NewCache(ctx)

	const url = "https://www.googleapis.com/oauth2/v3/certs"

	_ = cache.Register(url)
	if _, err := cache.Refresh(ctx, url); err != nil {
		// url is not a valid JWKS
		log.Fatalf("failed to refresh JWKS: %v", err)
	}

	set, err := cache.Get(ctx, url)
	if err != nil {
		log.Fatalf("failed to get JWKS: %v", err)
	}

	_ = set
}
```

--------------------------------

### WhitelistFunc IsAllowed method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Implements the IsAllowed method for WhitelistFunc. This allows defining custom logic to determine if a given URL can be fetched.

```go
func (w WhitelistFunc) IsAllowed(u string) bool
```

--------------------------------

### Create New AlgorithmSet

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/jose

Creates a new, empty AlgorithmSet. This function is useful for initializing a set of algorithms. Added in v2.0.9.

```go
func NewAlgorithmSet() *AlgorithmSet
```

--------------------------------

### Get a new map[string]error object

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/internal/pool

Acquires a reusable map[string]error object from the pool. Use this to avoid repeated allocations.

```go
func GetKeyToErrorMap() map[string]error
```

--------------------------------

### TokenOptionSet Set Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Replaces the entire option set with a new value. This is not the same as Enable/Disable.

```go
func (o *TokenOptionSet) Set(s TokenOptionSet)
```

--------------------------------

### Cache Register Method Signature

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Signature for the Register method of the Cache type. It registers a URL to be managed by the cache. URLs must be registered before Get is called.

```go
func (c *Cache) Register(u string, options ...RegisterOption) error
```

--------------------------------

### With Thumbprint Hash Option

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Returns an option that configures the hash algorithm used for key thumbprints.

```go
func WithThumbprintHash(v crypto.Hash) AssignKeyIDOption
```

--------------------------------

### Register Signature Algorithm with Options in Jwx

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwa

Registers a SignatureAlgorithm with optional configurations. This is an experimental function and may change.

```go
func RegisterSignatureAlgorithmWithOptions(v SignatureAlgorithm, options ...RegisterAlgorithmOption)
```

--------------------------------

### Content Encryption Algorithms

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwa

Defines ContentEncryptionAlgorithm type with constants for various AES-based encryption schemes. Provides functions to get all supported algorithms and to accept external values.

```APIDOC
## ContentEncryptionAlgorithm

### Description
Represents content encryption algorithms as defined in RFC 7518, Section 5.

### Constants
- `A128CBC_HS256`: AES-CBC + HMAC-SHA256 (128-bit).
- `A128GCM`: AES-GCM (128-bit).
- `A192CBC_HS384`: AES-CBC + HMAC-SHA384 (192-bit).
- `A192GCM`: AES-GCM (192-bit).
- `A256CBC_HS512`: AES-CBC + HMAC-SHA512 (256-bit).
- `A256GCM`: AES-GCM (256-bit).

### Functions
#### `ContentEncryptionAlgorithms()`
- **Description**: Returns a slice of all available `ContentEncryptionAlgorithm` values.
- **Signature**: `func ContentEncryptionAlgorithms() []ContentEncryptionAlgorithm`

#### `(*ContentEncryptionAlgorithm) Accept(value interface{}) error`
- **Description**: Used for converting values from external sources (like JSON payloads) into a `ContentEncryptionAlgorithm`.
- **Signature**: `func (v *ContentEncryptionAlgorithm) Accept(value interface{}) error`

#### `(ContentEncryptionAlgorithm) String() string`
- **Description**: Returns the string representation of a `ContentEncryptionAlgorithm`.
- **Signature**: `func (v ContentEncryptionAlgorithm) String() string`
```

--------------------------------

### Elliptic Curve Algorithms

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwa

Defines EllipticCurveAlgorithm type with constants for various elliptic curve cryptography algorithms. Provides functions to get all supported algorithms and to accept external values.

```APIDOC
## EllipticCurveAlgorithm

### Description
Represents algorithms used for Elliptic Curve keys.

### Constants
- `Ed25519`: Ed25519 algorithm.
- `Ed448`: Ed448 algorithm.
- `InvalidEllipticCurve`: Represents an invalid elliptic curve.
- `P256`: P-256 curve.
- `P384`: P-384 curve.
- `P521`: P-521 curve.
- `X25519`: X25519 algorithm.
- `X448`: X448 algorithm.

### Functions
#### `EllipticCurveAlgorithms()`
- **Description**: Returns a slice of all available `EllipticCurveAlgorithm` values.
- **Signature**: `func EllipticCurveAlgorithms() []EllipticCurveAlgorithm`

#### `(*EllipticCurveAlgorithm) Accept(value interface{}) error`
- **Description**: Used for converting values from external sources (like JSON payloads) into an `EllipticCurveAlgorithm`.
- **Signature**: `func (v *EllipticCurveAlgorithm) Accept(value interface{}) error`

#### `(EllipticCurveAlgorithm) String() string`
- **Description**: Returns the string representation of an `EllipticCurveAlgorithm`.
- **Signature**: `func (v EllipticCurveAlgorithm) String() string`
```

--------------------------------

### NewRegexpWhitelist Constructor

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Creates and returns a new instance of RegexpWhitelist.

```go
func NewRegexpWhitelist() *RegexpWhitelist
```

--------------------------------

### Implement Clock Interface with ClockFunc

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Makes a ClockFunc satisfy the Clock interface by implementing the Now() method.

```go
func (f ClockFunc) Now() time.Time
```

--------------------------------

### Get public keys from a JWK Set

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Returns a new jwk.Set containing only the public keys from the input set. This is useful for distributing public keys derived from a set of private keys.

```go
func PublicSetOf(v Set) (Set, error)
```

--------------------------------

### (SignatureAlgorithm).String()

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwa

String returns the string representation of a SignatureAlgorithm.

```APIDOC
## Method: (SignatureAlgorithm).String

### Description
Returns the string representation of a SignatureAlgorithm.

### Signature
```go
func (v SignatureAlgorithm) String() string
```

### Returns
- **string**: The string representation of the SignatureAlgorithm.
```

--------------------------------

### Specify compression algorithm for encryption

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe

Use WithCompress to specify the compression algorithm for encrypting a payload. Currently, only "" or "DEF" are supported.

```go
func WithCompress(v jwa.CompressionAlgorithm) EncryptOption
```

--------------------------------

### Get Public Key from Input

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Returns the corresponding public key for a given input. If the input is already a public key, it's returned directly. For symmetric keys or Ed25519, the byte slice is returned.

```go
func PublicRawKeyOf(v interface{}) (interface{}, error)
```

--------------------------------

### Equal

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Equal compares two keys and returns true if they are equal. The comparison is solely done against the thumbprints of k1 and k2. It is possible for keys that have, for example, different key IDs, key usage, etc, to be considered equal.

```APIDOC
## func Equal

### Description
Equal compares two keys and returns true if they are equal. The comparison is solely done against the thumbprints of k1 and k2. It is possible for keys that have, for example, different key IDs, key usage, etc, to be considered equal.

### Signature
```
func Equal(k1, k2 Key) bool
```
```

--------------------------------

### Builder Build Method

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/openid

Builds the JWT token from the claims set on the builder. Returns a nil Token and an error if any claim cannot be set.

```go
func (b *Builder) Build() (Token, error)
```

--------------------------------

### WithKeySet Option

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws

Specifies a JWKS (jwk.Set) for verification. By default, requires matching 'alg' and 'kid' fields. Suboptions can alter this behavior.

```go
func WithKeySet(set jwk.Set, options ...WithKeySetSuboption) VerifyOption
```

--------------------------------

### Create Encrypt Option

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt

Wraps a jwe.EncryptOption to be used as a jwt.EncryptOption. Typically not needed unless passing extra options to (jws.Serializer).Encrypt() via jwt.Sign().

```go
func WithEncryptOption(v jwe.EncryptOption) EncryptOption
```

--------------------------------

### Token Interface Definition

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt/openid

Defines the Token interface for JWTs, including methods to access standard claims like 'iss', 'aud', 'exp', and 'sub', as well as private claims. It also provides methods for getting, setting, removing claims, cloning tokens, and iterating through them.

```go
type Token interface {

	// Address returns the value for "address" field of the token
	Address() *AddressClaim

	// Audience returns the value for "aud" field of the token
	Audience() []string

	// Birthdate returns the value for "birthdate" field of the token
	Birthdate() *BirthdateClaim

	// Email returns the value for "email" field of the token
	Email() string

	// EmailVerified returns the value for "email_verified" field of the token
	EmailVerified() bool

	// Expiration returns the value for "exp" field of the token
	Expiration() time.Time

	// FamilyName returns the value for "family_name" field of the token
	FamilyName() string

	// Gender returns the value for "gender" field of the token
	Gender() string

	// GivenName returns the value for "given_name" field of the token
	GivenName() string

	// IssuedAt returns the value for "iat" field of the token
	IssuedAt() time.Time

	// Issuer returns the value for "iss" field of the token
	Issuer() string

	// JwtID returns the value for "jti" field of the token
	JwtID() string

	// Locale returns the value for "locale" field of the token
	Locale() string

	// MiddleName returns the value for "middle_name" field of the token
	MiddleName() string

	// Name returns the value for "name" field of the token
	Name() string

	// Nickname returns the value for "nickname" field of the token
	Nickname() string

	// NotBefore returns the value for "nbf" field of the token
	NotBefore() time.Time

	// PhoneNumber returns the value for "phone_number" field of the token
	PhoneNumber() string

	// PhoneNumberVerified returns the value for "phone_number_verified" field of the token
	PhoneNumberVerified() bool

	// Picture returns the value for "picture" field of the token
	Picture() string

	// PreferredUsername returns the value for "preferred_username" field of the token
	PreferredUsername() string

	// Profile returns the value for "profile" field of the token
	Profile() string

	// Subject returns the value for "sub" field of the token
	Subject() string

	// UpdatedAt returns the value for "updated_at" field of the token
	UpdatedAt() time.Time

	// Website returns the value for "website" field of the token
	Website() string

	// Zoneinfo returns the value for "zoneinfo" field of the token
	Zoneinfo() string

	// PrivateClaims return the entire set of fields (claims) in the token
	// *other* than the pre-defined fields such as `iss`, `nbf`, `iat`, etc.
	PrivateClaims() map[string]interface{}

	// Get returns the value of the corresponding field in the token, such as
	// `nbf`, `exp`, `iat`, and other user-defined fields. If the field does not
	// exist in the token, the second return value will be `false`
	//
	// If you need to access fields like `alg`, `kid`, `jku`, etc, you need
	// to access the corresponding fields in the JWS/JWE message. For this, 
	// you will need to access them by directly parsing the payload using
	// `jws.Parse` and `jwe.Parse`
	Get(string) (interface{}, bool)

	// Set assigns a value to the corresponding field in the token. Some
	// pre-defined fields such as `nbf`, `iat`, `iss` need their values to
	// be of a specific type. See the other getter methods in this interface
	// for the types of each of these fields
	Set(string, interface{}) error
	Remove(string) error

	// Options returns the per-token options associated with this token.
	// The options set value will be copied when the token is cloned via `Clone()`
	// but it will not survive when the token goes through marshaling/unmarshaling
	// such as `json.Marshal` and `json.Unmarshal`
	Options() *jwt.TokenOptionSet
	Clone() (jwt.Token, error)
	Iterate(context.Context) Iterator
	Walk(context.Context, Visitor) error
	AsMap(context.Context) (map[string]interface{}, error)
}
```

--------------------------------

### Get Public Key from JWK Key

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Use PublicKeyOf to retrieve the public version of a jwk.Key. For SymmetricKey, the same value is returned. If the input is already a public key, it's returned directly. For private keys with a PublicKey() method, fields are copied, and the caller must manage any necessary field removals.

```go
func PublicKeyOf(v interface{}) (Key, error)
```

--------------------------------

### Fetch Option: WithFetchWhitelist

Source: https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk

Specifies the Whitelist object to use when fetching JWKs from a remote source. This option can be passed to jwk.Fetch(), jwk.NewCache(), and (*jwk.Cache).Configure().

```go
func WithFetchWhitelist(v Whitelist) FetchOption
```
Tokens:
Raw