tls

README

darvaza.org/x/tls

Overview

The tls package provides advanced TLS/SSL certificate handling utilities that extend Go's standard crypto/tls package. It includes certificate stores, SNI inspection, certificate bundling, and enhanced x509 utilities with a focus on dynamic certificate management.

Features

• Dynamic Certificate Management: Add and remove certificates at runtime
• SNI Support: Parse and route based on Server Name Indication
• Certificate Bundling: Automatic certificate chain construction
• Enhanced X.509 Utilities: Advanced certificate manipulation

Components

Certificate Store

Dynamic certificate storage with multiple backend implementations.

// Create a store
store := &basic.Store{}
ctx := context.Background()

// Add certificates
err := store.AddCertPair(ctx, privateKey, cert, intermediates)

// Configure TLS
config := &tls.Config{
    GetCertificate: store.GetCertificate,
    RootCAs: store.GetCAPool(),
}

Certificate Bundling

Automatic certificate chain building with quality optimization.

bundler := &tls.Bundler{
    Roots: systemRoots,
    Inter: intermediateCerts,
    Less: func(a, b []*x509.Certificate) bool {
        // Prefer shorter chains
        return len(a) < len(b)
    },
}

// Bundle certificate with optimal chain
tlsCert, err := bundler.Bundle(cert, privateKey)

SNI Handling

Parse ClientHello packets without full TLS handshake.

// Parse SNI from ClientHello
info := sni.GetInfo(clientHelloBytes)
if info != nil {
    fmt.Printf("SNI: %s\n", info.ServerName)
}

// SNI-based routing
dispatcher := sni.NewDispatcher()
dispatcher.Add("example.com", exampleHandler)
dispatcher.Add("*.api.com", apiHandler)

Packages

sni

Server Name Indication parsing and routing.

• ClientHello parsing without full handshake
• SNI-based dispatching
• Chi router integration

store

Certificate storage implementations.

• basic: Simple in-memory store
• buffer: Buffered certificate operations
• config: Configuration-based loading

x509utils

Enhanced X.509 certificate utilities.

• certpool: Advanced certificate pool management
• PEM encoding/decoding
• Certificate validation
• System certificate integration

Examples

Working with Certificate Pools

// Create custom cert pool
pool := certpool.New()
pool.AddCert(rootCA)

// Clone and extend system pool
sysPool, _ := certpool.SystemCertPool()
customPool := sysPool.Clone()
customPool.AddCert(internalCA)

PEM Operations

// Read PEM files
certs, err := x509utils.ReadCertificates(pemData)
key, err := x509utils.ReadPrivateKey(keyData)

// Write PEM
pemData := x509utils.EncodeCertificates(certs...)
keyData := x509utils.EncodePrivateKey(key)

Custom Verification

err := tls.Verify(cert, &tls.VerifyOptions{
    DNSName: "example.com",
    Roots: customRoots,
    Intermediates: customInter,
})

Installation

go get darvaza.org/x/tls

Dependencies

• darvaza.org/core: Core utilities
• golang.org/x/crypto: Low-level crypto parsing
• Standard library (crypto/tls, crypto/x509)

Security Considerations

• Private keys are stored in memory (consider HSM for production)
• Certificate validation follows standard x509 rules
• SNI parsing is resistant to malformed packets
• System cert pool access may require elevated privileges

Development

For development guidelines, architecture notes, and AI agent instructions, see AGENT.md.

License

See LICENCE.txt for details.

Documentation

Overview

Package tls aids working with TLS Certificates

Index

• Variables
• func Bundle(opt x509.VerifyOptions, cert *x509.Certificate, key x509utils.PrivateKey) (*tls.Certificate, error)
• func BundleFn(opt x509.VerifyOptions, less func(a, b []*x509.Certificate) bool, ...) (*tls.Certificate, error)
• func NewConfig(store Store) (*tls.Config, error)
• func SplitClientHelloInfo(chi *tls.ClientHelloInfo) (ctx context.Context, serverName string, err error)
• func Verify(cert *tls.Certificate, roots *x509.CertPool) error
• func WithStore(cfg *tls.Config, store Store) error
• type Bundler
  • func (s *Bundler) Bundle(cert *x509.Certificate, key x509utils.PrivateKey) (*tls.Certificate, error)
  • func (s *Bundler) Reset()
• type Certificate
• type ClientHelloInfo
• type Config
• type Store
• type StoreReadWriter
• type StoreReader
• type StoreWriter
• type StoreX509Writer

Variables

var ErrNoStore = core.Wrap(core.ErrInvalid, "store not provided")

ErrNoStore is an error indicating the Store wasn't provided.

Functions

func Bundle

func Bundle(opt x509.VerifyOptions, cert *x509.Certificate, key x509utils.PrivateKey) (*tls.Certificate, error)

Bundle assembles a verified tls.Certificate, choosing the shortest trust chain.

func BundleFn

func BundleFn(opt x509.VerifyOptions, less func(a, b []*x509.Certificate) bool,
	cert *x509.Certificate, key x509utils.PrivateKey) (*tls.Certificate, error)

BundleFn assembles a verified tls.Certificate, using the given quality function.

func NewConfig

func NewConfig(store Store) (*tls.Config, error)

NewConfig returns a basic tls.Config optionally configured to use the given Store.

func SplitClientHelloInfo

func SplitClientHelloInfo(chi *tls.ClientHelloInfo) (ctx context.Context, serverName string, err error)

SplitClientHelloInfo takes the context and server name out of a tls.ClientHelloInfo. If no ServerName is provided, the server's IP address will be used.

func Verify

func Verify(cert *tls.Certificate, roots *x509.CertPool) error

Verify checks if a tls.Certificate is good to use. If roots is provided, the chain will also be verified.

func WithStore

func WithStore(cfg *tls.Config, store Store) error

WithStore binds a given Store to the tls.Config

Types

type Bundler

type Bundler struct {
	// Root Certificates. Defaults to system's.
	Roots x509utils.CertPool
	// Intermediate Certificates.
	Inter x509utils.CertPool
	// Quality comparison function. Defaults to shorter-chain.
	Less func(a, b []*x509.Certificate) bool
	// contains filtered or unexported fields
}

Bundler uses two CertPools to bundle keys and certificates

func (*Bundler) Bundle

func (s *Bundler) Bundle(cert *x509.Certificate, key x509utils.PrivateKey) (*tls.Certificate, error)

Bundle bundles a key and a certificate into a tls.Certificate using the specified roots, intermediates and quality function.

func (*Bundler) Reset

func (s *Bundler) Reset()

Reset drops any cached information.

type Certificate

type Certificate = tls.Certificate

Certificate is an alias of the standard tls.Certificate

type ClientHelloInfo

type ClientHelloInfo = tls.ClientHelloInfo

ClientHelloInfo is an alias of the standard tls.ClientHelloInfo.

type Config

type Config = tls.Config

Config is an alias of the standard tls.Config

type Store

type Store interface {
	GetCertificate(*tls.ClientHelloInfo) (*tls.Certificate, error)
	GetCAPool() *x509.CertPool
}

A Store is used to set up a tls.Config.

type StoreReadWriter

type StoreReadWriter interface {
	StoreReader
	StoreWriter
}

StoreReadWriter includes read and write methods for the Store

type StoreReader

type StoreReader interface {
	Store

	Get(ctx context.Context, name string) (*tls.Certificate, error)

	ForEach(ctx context.Context, fn func(context.Context, *tls.Certificate) bool)
	ForEachMatch(ctx context.Context, name string, fn func(context.Context, *tls.Certificate) bool)
}

StoreReader adds read methods to the Store.

type StoreWriter

type StoreWriter interface {
	Store

	Put(ctx context.Context, cert *tls.Certificate) error
	Delete(ctx context.Context, cert *tls.Certificate) error
}

StoreWriter adds tls.Certificate write methods to the Store.

type StoreX509Writer

type StoreX509Writer interface {
	Store

	AddCACerts(ctx context.Context, roots ...*x509.Certificate) error

	AddPrivateKey(ctx context.Context, key crypto.Signer) error
	AddCert(ctx context.Context, cert *x509.Certificate) error
	AddCertPair(ctx context.Context, key crypto.Signer, cert *x509.Certificate, intermediates []*x509.Certificate) error

	DeleteCert(ctx context.Context, cert *x509.Certificate) error
}

StoreX509Writer adds x509.Certificate write methods to the Store.