1 package jwk 2 3 import ( 4 "context" 5 "crypto/x509" 6 "net/http" 7 "sync" 8 9 "github.com/lestrrat-go/iter/arrayiter" 10 "github.com/lestrrat-go/iter/mapiter" 11 "github.com/lestrrat-go/jwx/internal/iter" 12 "github.com/lestrrat-go/jwx/internal/json" 13 ) 14 15 // KeyUsageType is used to denote what this key should be used for 16 type KeyUsageType string 17 18 const ( 19 // ForSignature is the value used in the headers to indicate that 20 // this key should be used for signatures 21 ForSignature KeyUsageType = "sig" 22 // ForEncryption is the value used in the headers to indicate that 23 // this key should be used for encrypting 24 ForEncryption KeyUsageType = "enc" 25 ) 26 27 type CertificateChain struct { 28 certs []*x509.Certificate 29 } 30 31 type KeyOperation string 32 type KeyOperationList []KeyOperation 33 34 const ( 35 KeyOpSign KeyOperation = "sign" // (compute digital signature or MAC) 36 KeyOpVerify KeyOperation = "verify" // (verify digital signature or MAC) 37 KeyOpEncrypt KeyOperation = "encrypt" // (encrypt content) 38 KeyOpDecrypt KeyOperation = "decrypt" // (decrypt content and validate decryption, if applicable) 39 KeyOpWrapKey KeyOperation = "wrapKey" // (encrypt key) 40 KeyOpUnwrapKey KeyOperation = "unwrapKey" // (decrypt key and validate decryption, if applicable) 41 KeyOpDeriveKey KeyOperation = "deriveKey" // (derive key) 42 KeyOpDeriveBits KeyOperation = "deriveBits" // (derive bits not to be used as a key) 43 ) 44 45 // Set represents JWKS object, a collection of jwk.Key objects. 46 // 47 // Sets can be safely converted to and from JSON using the standard 48 // `"encoding/json".Marshal` and `"encoding/json".Unmarshal`. However, 49 // if you do not know if the payload contains a single JWK or a JWK set, 50 // consider using `jwk.Parse()` to always get a `jwk.Set` out of it. 51 // 52 // Since v1.2.12, JWK sets with private parameters can be parsed as well. 53 // Such private parameters can be accessed via the `Field()` method. 54 // If a resource contains a single JWK instead of a JWK set, private parameters 55 // are stored in _both_ the resulting `jwk.Set` object and the `jwk.Key` object . 56 // 57 type Set interface { 58 // Add adds the specified key. If the key already exists in the set, it is 59 // not added. 60 // This method will be renamed to `AddKey(Key)` in a future major release. 61 Add(Key) bool 62 63 // Clear resets the list of keys associated with this set, emptying the 64 // internal list of `jwk.Key`s 65 // This method will be changed in the future to clear all contents in the 66 // `jwk.Set` instead of just the keys. 67 Clear() 68 69 // Get returns the key at index `idx`. If the index is out of range, 70 // then the second return value is false. 71 // This method will be renamed to `Key(int)` in a future major release. 72 Get(int) (Key, bool) 73 74 // Field returns the value of a private field in the key set. 75 // 76 // For the purposes of a key set, any field other than the "keys" field is 77 // considered to be a private field. In other words, you cannot use this 78 // method to directly access the list of keys in the set 79 // 80 // This method will be renamed to `Get(string)` in a future major release. 81 Field(string) (interface{}, bool) 82 83 // Set sets the value of a single field. 84 // 85 // This method, which takes an `interface{}`, exists because 86 // these objects can contain extra _arbitrary_ fields that users can 87 // specify, and there is no way of knowing what type they could be. 88 Set(string, interface{}) error 89 90 // Remove removes the field associated with the specified key. 91 // There is no way to remove the `kty` (key type). You will ALWAYS be left with one field in a jwk.Key. 92 // Index returns the index where the given key exists, -1 otherwise 93 Index(Key) int 94 95 // Len returns the number of keys in the set 96 Len() int 97 98 // LookupKeyID returns the first key matching the given key id. 99 // The second return value is false if there are no keys matching the key id. 100 // The set *may* contain multiple keys with the same key id. If you 101 // need all of them, use `Iterate()` 102 LookupKeyID(string) (Key, bool) 103 104 // Remove removes the key from the set. 105 Remove(Key) bool 106 107 // Iterate creates an iterator to iterate through all keys in the set. 108 Iterate(context.Context) KeyIterator 109 110 // Clone create a new set with identical keys. Keys themselves are not cloned. 111 Clone() (Set, error) 112 } 113 114 type set struct { 115 keys []Key 116 mu sync.RWMutex 117 dc DecodeCtx 118 privateParams map[string]interface{} 119 } 120 121 type HeaderVisitor = iter.MapVisitor 122 type HeaderVisitorFunc = iter.MapVisitorFunc 123 type HeaderPair = mapiter.Pair 124 type HeaderIterator = mapiter.Iterator 125 type KeyPair = arrayiter.Pair 126 type KeyIterator = arrayiter.Iterator 127 128 type PublicKeyer interface { 129 // PublicKey creates the corresponding PublicKey type for this object. 130 // All fields are copied onto the new public key, except for those that are not allowed. 131 // Returned value must not be the receiver itself. 132 PublicKey() (Key, error) 133 } 134 135 // HTTPClient specifies the minimum interface that is required for our JWK 136 // fetching tools. 137 type HTTPClient interface { 138 Do(*http.Request) (*http.Response, error) 139 } 140 141 type DecodeCtx interface { 142 json.DecodeCtx 143 IgnoreParseError() bool 144 } 145 type KeyWithDecodeCtx interface { 146 SetDecodeCtx(DecodeCtx) 147 DecodeCtx() DecodeCtx 148 } 149 150 type AutoRefreshError struct { 151 Error error 152 URL string 153 } 154 155 // Whitelist is an interface for a set of URL whitelists. When provided 156 // to JWK fetching operations, urls are checked against this object, and 157 // the object must return true for urls to be fetched. 158 type Whitelist interface { 159 IsAllowed(string) bool 160 } 161