jw509json

README

x509 JSON

import "github.com/a-novel-kit/jwt-core/x509/json"

Handlers for the JSON Web Algorithm representation of certificates.

Verify

When receiving certificate information in a JSON Web object, it is important to validate its integrity.

certs, err := jw509json.Verify(certs, &jw509json.VerifyConfig{
	ReqFactory: jw509json.RequestFactoryDefault,
})

This method returns the decoded list of certificates on success, so they can be used to validate the key.

Retrieving remote certificates

When serving certificates over HTTP with the x5u member, the RFC specification requires the usage of TLS. You might also want to add extra security layers, in the form of authentication or custom headers.

Thus, you must provide a *http.Request builder for this method to safely retrieve your keys. This method takes a jw509json.Payload as an input, and returns a *http.Request.

func MyReqBuilder(payload *jw509json.Payload) (*http.Request, error) {
	req, err := http.NewRequest("GET", payload.X5u, nil)
	if err != nil {
		return nil, err
	}

	// Do stuff with your request
	
	return req, nil
}

You can use the default jw509json.RequestFactoryDefault for quick configuration, however beware this does not use any security layer.

Further validate integrity of the certificate chain

The default Verify behavior performs some quick integrity checks (thumbprints validation, and sources matching). However, the payload itself may lack information (all fields are optional), and even so, there is no guarantee the source certificate was valid to begin with.

It is recommended to set up extra configuration to validate the certificate chain itself. You can do so by passing in a configuration for the jw509.Validate method.

certs, err := jw509json.Verify(certs, &jw509json.VerifyConfig{
	ReqFactory: jw509json.RequestFactoryDefault,
	ValidateConfig: &jw509.ValidateConfig{
		// Restrict the trusted origins of the certificates.
		TrustedHostnames: []string{"example.com"},
	},
})

Generate

You can create a configuration from your own certificates, so third party can also validate your certificates.

payload, err := jw509json.Generate(certs, &jw509json.GenerateConfig{
	Embed: true,
	Serve: "https://example.com/certificates",
	Thumbprint: true,
	Thumbprint256: true,
})

All members are optional, so you can choose what will appear on the final payload. The payload can be embedded directly in your JWT.

Documentation

Index

• Variables
• func Generate(src []*x509.Certificate, config *GenerateConfig) (*jwa.J509, error)
• func RequestFactoryDefault(ctx context.Context, src *jwa.J509) (*http.Request, error)
• func Verify(ctx context.Context, src *jwa.J509, config *VerifyConfig) ([]*x509.Certificate, error)
• type GenerateConfig
• type VerifyConfig

Variables

var (
	ErrNoCert           = errors.New("no certificate chain provided")
	ErrUnexpectedStatus = errors.New("unexpected status code")
)

Functions

func Generate

func Generate(src []*x509.Certificate, config *GenerateConfig) (*jwa.J509, error)

Generate a new X509 JSON payload for a certificate chain.

func RequestFactoryDefault

func RequestFactoryDefault(ctx context.Context, src *jwa.J509) (*http.Request, error)

func Verify

func Verify(ctx context.Context, src *jwa.J509, config *VerifyConfig) ([]*x509.Certificate, error)

Verify ensures the represented certificate chain is valid.

Types

type GenerateConfig

type GenerateConfig struct {
	// Embed embeds the certificate chain in the JWT.
	Embed bool
	// Serve indicates a URL on which certificates will be served.
	Serve string

	// Thumbprint generates a sha1 thumbprint of the certificate chain.
	Thumbprint bool
	// Thumbprint256 generates a sha256 thumbprint of the certificate chain.
	Thumbprint256 bool
}

type VerifyConfig

type VerifyConfig struct {
	// Validate is an optional config to ensure the certificate chain is valid.
	Validate *jwx509.ValidateConfig
	// ReqFactory is a function to create the request to fetch the remote certificate chain.
	//
	// While required, you can use the default RequestFactoryDefault for faster setup. This is however not recommended,
	// as the URL that serves your certificates must provide a layer of security that should be embedded in that
	// request.
	ReqFactory func(ctx context.Context, src *jwa.J509) (*http.Request, error)
}