tlscfg

README

tlscfg

This repo provides an option-driven Go package that simplifies initializing a well configured *tls.Config.

Initializing a *tls.Config is a rote task, and often good, secure defaults are not so obvious. This package aims to eliminate the chore of initializing a *tls.Config correctly and securely.

New returns a valid config with system certificates and tls v1.2+ ciphers. The With functions can be used to further add certificates or override settings as appropriate.

Usage:

cfg, err := tlscfg.New(
        tlscfg.MaybeWithDiskCA( // optional CA
                *flagCA,
                tlscfg.ForClient,
        ),
        tlscfg.WithDiskKeyPair( // required client cert+key pair
                "cert.pem",
                "key.pem",
        ),
)
if err != nil {
        // handle
}

Documentation

Overview

Package tlscfg provides an option-driven way to easily setup a well configured *tls.Config.

Initializing a *tls.Config is a rote task, and often good, secure defaults are not so obvious. This package aims to eliminate the chore of initializing a *tls.Config correctly and securely.

New returns a valid config with system certificates and tls v1.2+ ciphers. The With functions can be used to further add certificates or override settings as appropriate.

Usage:

cfg, err := tlscfg.New(
        tlscfg.MaybeWithDiskCA( // optional CA
                *flagCA,
                tlscfg.ForClient,
        ),
        tlscfg.WithDiskKeyPair( // required client cert+key pair
                "cert.pem",
                "key.pem",
        ),
)
if err != nil {
        // handle
}

Index

• func CipherSuites() []uint16
• func CurvePreferences() []tls.CurveID
• func New(opts ...Opt) (*tls.Config, error)
• type FS
  • func FuncFS(fn func(path string) ([]byte, error)) FS
• type ForKind
• type Opt
  • func MaybeWithDiskCA(path string, forKind ForKind) Opt
  • func MaybeWithDiskKeyPair(certPath, keyPath string) Opt
  • func WithAdditionalCipherSuites(cipherSuites ...uint16) Opt
  • func WithCA(ca []byte, forKind ForKind) Opt
  • func WithDiskCA(path string, forKind ForKind) Opt
  • func WithDiskKeyPair(certPath, keyPath string) Opt
  • func WithFS(fs FS) Opt
  • func WithKeyPair(cert, key []byte) Opt
  • func WithOverride(fn func(*tls.Config) error) Opt
  • func WithServerName(name string) Opt
  • func WithSystemCertPool() Opt

Functions

func CipherSuites

func CipherSuites() []uint16

CipherSuites returns this package's recommended ciphers that tls configurations should use.

Currently, this returns tls ciphers that are only compatible with tls v1.2. Ciphers for tls v1.3 are not include because if a connection negotiates tls v1.3, Go internally uses v1.3 ciphers.

func CurvePreferences

func CurvePreferences() []tls.CurveID

CurvePreferences returns this package's recommended curve preferences that tls configurations should use.

Currently, this returns only x25519. This may cause problems with old versions of openssl, if so, be sure to add P256.

This package by default does not set CurvePreferences, relying on the Go default. However, you can opt into this package's CurvePreferences for added paranoia.

func New

func New(opts ...Opt) (*tls.Config, error)

New creates and returns a *tls.Config with any options applied.

This function will not error if no options are specified.

Types

type FS

type FS interface {
	// ReadFile opens the file at path and reads it.
	ReadFile(path string) ([]byte, error)
}

FS represents a filesystem.

This is different from fs.FS, because fs.FS only reads unrooted paths.

func FuncFS

func FuncFS(fn func(path string) ([]byte, error)) FS

FuncFS returns a FS that reads a file using the given function.

type ForKind

type ForKind uint8

ForKind is used in some options to specify whether the option is meant to be applied for server configurations or client configurations.

const (
	// ForServer specifies that an option should work on server portions
	// of a *tls.Config (adding a CA).
	ForServer ForKind = iota
	// ForClient specifies that an option should work on client portions
	// of a *tls.Config (adding a CA).
	ForClient
)

type Opt

type Opt interface {
	// contains filtered or unexported methods
}

Opt is a function to configure a *tls.Config.

func MaybeWithDiskCA

func MaybeWithDiskCA(path string, forKind ForKind) Opt

MaybeWithDiskCA optionally loads a PEM encoded CA cert from disk and adds it to the proper CA pool based off of forKind.

If the path is empty, this option does nothing. This option is useful if accepting flags to optionally setup a cert.

NOTE: If this option loads a CA, then system certs are not used. If you wish to use system certs in addition to this CA, use the WithSystemCertPool option.

func MaybeWithDiskKeyPair

func MaybeWithDiskKeyPair(certPath, keyPath string) Opt

MaybeWithDiskKeyPair optionally loads a PEM encoded cert and key from certPath and keyPath and adds the pair to the *tls.Config's Certificates.

If both certPath and keyPath are empty, this option does nothing. This option is useful if accepting flags to optionally setup a cert.

func WithAdditionalCipherSuites

func WithAdditionalCipherSuites(cipherSuites ...uint16) Opt

WithAdditionalCipherSuites adds additional cipher suites to the default set used by this package. This option is important if talking to legacy systems that do not support newer cipher suites.

func WithCA

func WithCA(ca []byte, forKind ForKind) Opt

WithCA parses a PEM encoded CA cert and adds it to the proper CA pool based off of forKind.

If for servers, this option sets RequireAndVerifyClientCert.

NOTE: This option ensures system certs are not used. If you wish to use system certs in addition to this CA, use the WithSystemCertPool option.

func WithDiskCA

func WithDiskCA(path string, forKind ForKind) Opt

WithDiskCA loads a PEM encoded CA cert from disk and adds it to the proper CA pool based off of forKind.

If for servers, this option sets RequireAndVerifyClientCert.

NOTE: This option ensures system certs are not used. If you wish to use system certs in addition to this CA, use the WithSystemCertPool option.

func WithDiskKeyPair

func WithDiskKeyPair(certPath, keyPath string) Opt

WithDiskKeyPair loads a PEM encoded cert and key from certPath and keyPath and adds the pair to the *tls.Config's Certificates.

func WithFS

func WithFS(fs FS) Opt

WithFS sets the filesystem used to read files, overriding the default of simply using the host OS.

func WithKeyPair

func WithKeyPair(cert, key []byte) Opt

WithKeyPair parses a PEM encoded cert and key and adds the pair to the *tls.Config's Certificates.

func WithOverride

func WithOverride(fn func(*tls.Config) error) Opt

WithOverride returns an option to override fields on a *tls.Config. All overrides are run last, in order.

func WithServerName

func WithServerName(name string) Opt

WithServerName sets the *tls.Config's ServerName, which is important for clients to verify servers. This option is required if all of the following are true:

• the config is not used in an http.Transport (http.Transport clones the config and sets ServerName)
• you do not set InsecureSkipVerify to true
• you do not want to set ServerName on the config manually

func WithSystemCertPool

func WithSystemCertPool() Opt

WithSystemCertPool ensures that the system cert pool is used in addition to any CA you manually set.

This option is necessary if you want to talk to both servers that have public CA issued certs as well as servers that have your own manually issued certs, or, as a server, if you want to verify certs from clients with public CA issued certs as well as clients that use custom certs.

This option is likely only to be used when migrating from mTLS custom certs to public CA certs.

Only cert pools that have additional CAs to add are initialized. If no extra CAs are added, the pool is left nil, which by default uses system certs.