jwks

README

jwks

Package jwks provides low level facilities for parsing JWKs endpoint responses according to RFC7517. It provides the basic JWK and JWK Set (JWKS) JSON parsing structs Response (keys) and Key ([]key). It also provides a small utility function and interface to obtain and parse a JWKS endpoint over string defined locations such as via URLs for HTTP(S).

This package aims to have as few dependencies as possible. It is meant to be the base building block for something grander.

Add To Your Project:

go get -u github.com/openziti/jwks@latest

Basic resolver usage:

resolver := &HttpResolver{}
resp, rawPayload, err := resolver.Get("https://myhost/.well-known/jwks.json")

Basic parser usage:

response := &Response{}
err := json.Unmarshal([]byte(`{"keys": [...]}`), response)

Documentation

Overview

Package jwks provides low level facilities for parsing JWKs endpoint responses according to RFC7517. It provides the basic JWK and JWK Set (JWKS) JSON parsing structs Response (`keys`) and Key (`[]key`). It also provides a small utility function and interface to obtain and parse a JWKS endpoint over string defined locations such as via URLs for HTTP(S).

Basic resolver usage: ```

resolver := &HttpResolver{}
resp, rawPayload, err := resolver.Get("https://myhost/.well-known/jwks.json")

``` Basic parser usage: ```

response := &Response{}
err := json.Unmarshal([]byte(`{"keys": [...]}`), response)

```

Copyright NetFoundry, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Constants
• func KeyToPublicKey(key Key) (interface{}, error)
• type HttpResolver
  • func (j *HttpResolver) Get(url string) (*Response, []byte, error)
• type HttpResolverError
• type Key
  • func NewKey(keyId string, cert *x509.Certificate, chain []*x509.Certificate) (*Key, error)
• type Resolver
• type Response

Constants

const (
	KeyTypeRsa = "RSA"
	KeyTypeEc  = "EC"
)

const (
	ErrorInvalidStatusCodeMsg  = "could not fetch JWKS, status code was not 200 OK"
	ErrorInvalidContentTypeMsg = "invalid content type, expected application/json"
)

Functions

func KeyToPublicKey

func KeyToPublicKey(key Key) (interface{}, error)

KeyToPublicKey converts the JSON marshalled Key to an interface{} object which represents a public key that may be backed by rsa.PublicKey or ecdsa.Public key depending on the input key's KeyType.

Types

type HttpResolver

type HttpResolver struct{}

HttpResolver implements Resolver and obtains JWKs responses via HTTP(S)

func (*HttpResolver) Get

func (j *HttpResolver) Get(url string) (*Response, []byte, error)

type HttpResolverError

type HttpResolverError struct {
	Resp *http.Response
	// contains filtered or unexported fields
}

HttpResolverError is a generic error type used to relay the the http.Response from a JWKS endpoint to external code for inspection

type Key

type Key struct {
	Algorithm     string   `json:"alg"`     // https://www.rfc-editor.org/rfc/rfc7518#section-3.1
	KeyType       string   `json:"kty"`     // RSA, EC
	KeyOperations []string `json:"key_ops"` // sign, verify, encrypt, decrypt, wrapKey, unwrapKey, deriveKey, deriveBits
	Use           string   `json:"use"`     // sig, enc
	KeyId         string   `json:"kid"`     // a unique id for a key

	//x509
	X509Thumbprint       string   `json:"x5t"`      //sha1 of der bytes
	X509ThumbprintSha256 string   `json:"x5t#S256"` //sha256 of der bytes
	X509Chain            []string `json:"x5c"`      // array of base64 certificate DER
	X509Url              string   `json:"x5u"`      // URI pointing to an array of pem certs

	//public ec kty="ec"
	Curve string `json:"crv"` //ec curve
	X     string `json:"x"`   // ec x curve coordinate
	Y     string `json:"y"`   // ec y curve coordinate

	//public rsa kty="rsa"
	N string `json:"n"` // rsa modulus
	E string `json:"e"` // rsa public exponent

	//symmetric kty="oct"
	K string `json:"k"` // symmetric key

	//private key properties
	D  string `json:"d"`  // rsa private exponent / ec private key
	P  string `json:"p"`  // rsa secret prime
	Q  string `json:"q"`  // rsa secret prime
	Dp string `json:"dp"` // rsa private key parameter
	Dq string `json:"dq"` // rsa private key parameter
	Qi string `json:"qi"` // rsa private key parameter

	//byok
	T string `json:"t"` //bring your own key property
}

Key is used to parse the public keys ina JWKS endpoint. All properties defined by https://www.rfc-editor.org/rfc/rfc7517#section-4.1 and https://www.rfc-editor.org/rfc/rfc7518

func NewKey

func NewKey(keyId string, cert *x509.Certificate, chain []*x509.Certificate) (*Key, error)

NewKey will convert an *x509.Certificate to a Key. If keyId is empty string, the keyId will be populated with the sha1 fingerprint/thumbprint of the certificate. Supports RSA and EC keys only.

type Resolver

type Resolver interface {
	Get(string) (*Response, []byte, error)
}

Resolver takes in a string location and returns the Response and raw response (`[]byte`) JSON or an error

type Response

type Response struct {
	Keys []Key `json:"keys"`
}

Response is used to parse a JWKS endpoint response, it contains zero or more Key instances