jwx509

README

x509

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

Manage certificates using x509 package.

• Thumbprint
• Validate
  • Validate options

Thumbprint

To prevent tampering with certificates, JWA provides options to pass Thumbprints, to ensure the data integrity of the certificates.

You can use the MatchThumbprint method to validate those. The thumbprint must be either 20 bytes long (for sha1) or 32 bytes long (for sha256).

// It returns jw509.ErrThumbprintMismatch if the thumbprints do not match.
err := jw509.MatchThumbprint(certs, thumbprint)

Validate

While certificates are used to ensure the integrity of a key, it is also useful to ensure the integrity of the certificates themselves.

While the MatchThumbprint does that partially, it only does so on the first certificate of the chain. Validate provides a (complementary) deeper check, that validates the entire chain.

Unlike other methods, it also requires that you pass a configuration object.

err := jw509.Validate(certs, &jw509.ValidateConfig{})

Validate options

While an empty config works, it is recommended to provide some extra constraints when checking the certificates.

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

You can have a look at the complete options from the struct documentation directly.

Documentation

Index

• Variables
• func MatchThumbprint(certs []*x509.Certificate, thumbprint []byte) error
• func Validate(certs []*x509.Certificate, opts *ValidateConfig) error
• type ValidateConfig

Variables

var (
	ErrNoCerts            = errors.New("no certificates provided")
	ErrThumbprintMismatch = errors.New("thumbprint mismatch")
)

var ErrInvalidCertHost = errors.New("certificate was not issued for any of the provided hostnames")

Functions

func MatchThumbprint

func MatchThumbprint(certs []*x509.Certificate, thumbprint []byte) error

MatchThumbprint checks if the thumbprint of the first certificate in the chain matches the provided thumbprint.

The thumbprint must be either 20 bytes long (for sha1) or 32 bytes long (for sha256).

func Validate

func Validate(certs []*x509.Certificate, opts *ValidateConfig) error

Validate checks the integrity of a certificate chain.

Types

type ValidateConfig

type ValidateConfig struct {
	// TrustedHostnames, if present, will ensure the certificates are issued from one of the provided hostnames.
	TrustedHostnames []string
	// Usage specifies which Extended CEK Usage values are acceptable. A chain is accepted if it allows any of the
	// listed values. An empty list means x509.ExtKeyUsageServerAuth. To accept any key usage, include
	// x509.ExtKeyUsageAny.
	Usage []x509.ExtKeyUsage
	// CurrentTime is used to check the validity of all certificates in the chain. If zero, the current time is used.
	CurrentTime time.Time
	// Roots is the set of trusted root certificates the leaf certificate needs to chain up to. If nil, the system
	// roots or the platform verifier are used.
	Roots *x509.CertPool
}