option.go

Documentation: github.com/lestrrat-go/jwx/jws

     1  package jws
     2  
     3  import (
     4  	"net/http"
     5  
     6  	"github.com/lestrrat-go/backoff/v2"
     7  	"github.com/lestrrat-go/jwx/jwk"
     8  	"github.com/lestrrat-go/option"
     9  )
    10  
    11  type Option = option.Interface
    12  
    13  type identPayloadSigner struct{}
    14  type identDetachedPayload struct{}
    15  type identHeaders struct{}
    16  type identMessage struct{}
    17  type identFetchBackoff struct{}
    18  type identFetchWhitelist struct{}
    19  type identHTTPClient struct{}
    20  type identJWKSetFetcher struct{}
    21  
    22  func WithSigner(signer Signer, key interface{}, public, protected Headers) Option {
    23  	return option.New(identPayloadSigner{}, &payloadSigner{
    24  		signer:    signer,
    25  		key:       key,
    26  		protected: protected,
    27  		public:    public,
    28  	})
    29  }
    30  
    31  type SignOption interface {
    32  	Option
    33  	signOption()
    34  }
    35  
    36  type signOption struct {
    37  	Option
    38  }
    39  
    40  func (*signOption) signOption() {}
    41  
    42  // WithHeaders allows you to specify extra header values to include in the
    43  // final JWS message
    44  func WithHeaders(h Headers) SignOption {
    45  	return &signOption{option.New(identHeaders{}, h)}
    46  }
    47  
    48  // VerifyOption describes an option that can be passed to the jws.Verify function
    49  type VerifyOption interface {
    50  	Option
    51  	verifyOption()
    52  }
    53  
    54  type verifyOption struct {
    55  	Option
    56  }
    57  
    58  func (*verifyOption) verifyOption() {}
    59  
    60  // WithMessage can be passed to Verify() to obtain the jws.Message upon
    61  // a successful verification.
    62  func WithMessage(m *Message) VerifyOption {
    63  	return &verifyOption{option.New(identMessage{}, m)}
    64  }
    65  
    66  type SignVerifyOption interface {
    67  	SignOption
    68  	VerifyOption
    69  }
    70  
    71  type signVerifyOption struct {
    72  	Option
    73  }
    74  
    75  func (*signVerifyOption) signOption()   {}
    76  func (*signVerifyOption) verifyOption() {}
    77  
    78  // WithDetachedPayload can be used to both sign or verify a JWS message with a
    79  // detached payload.
    80  //
    81  // When this option is used for `jws.Sign()`, the first parameter (normally the payload)
    82  // must be set to `nil`.
    83  //
    84  // If you have to verify using this option, you should know exactly how and why this works.
    85  func WithDetachedPayload(v []byte) SignVerifyOption {
    86  	return &signVerifyOption{option.New(identDetachedPayload{}, v)}
    87  }
    88  
    89  // WithFetchWhitelist specifies the whitelist object to be passed
    90  // to `jwk.Fetch()` when `jws.VerifyAuto()` is used. If you do not
    91  // specify a whitelist, `jws.VerifyAuto()` will ALWAYS fail.
    92  //
    93  // This option is ignored if WithJWKSetFetcher is specified.
    94  func WithFetchWhitelist(wl jwk.Whitelist) VerifyOption {
    95  	return &verifyOption{option.New(identFetchWhitelist{}, wl)}
    96  }
    97  
    98  // WithFetchBackoff specifies the backoff.Policy object to be passed
    99  // to `jwk.Fetch()` when `jws.VerifyAuto()` is used.
   100  //
   101  // This option is ignored if WithJWKSetFetcher is specified.
   102  func WithFetchBackoff(b backoff.Policy) VerifyOption {
   103  	return &verifyOption{option.New(identFetchBackoff{}, b)}
   104  }
   105  
   106  // WithHTTPClient specifies the *http.Client object to be passed
   107  // to `jwk.Fetch()` when `jws.VerifyAuto()` is used.
   108  //
   109  // This option is ignored if WithJWKSetFetcher is specified.
   110  func WithHTTPClient(httpcl *http.Client) VerifyOption {
   111  	return &verifyOption{option.New(identHTTPClient{}, httpcl)}
   112  }
   113  
   114  // WithJWKSetFetcher specifies the JWKSetFetcher object to be
   115  // used when `jws.VerifyAuto()`, for example, to use `jwk.AutoRefetch`
   116  // instead of the default `jwk.Fetch()`
   117  func WithJWKSetFetcher(f JWKSetFetcher) VerifyOption {
   118  	return &verifyOption{option.New(identJWKSetFetcher{}, f)}
   119  }
   120
View as plain text