tlsconfig

Documentation

Overview

Package tlsconfig provides a safe set of TLS configurations for the Mozilla recommended ciphersuites. It also contains the Salesforce recommended TLS ciphersuites.

See https://wiki.mozilla.org/Security/Server_Side_TLS

Prioritized by:

Key Ex:   ECDHE > DH > RSA
Enc:      CHACHA20 > AES-GCM > AES-CBC > 3DES
MAC:      AEAD > SHA256 > SHA384 > SHA1 (SHA)
AES:      128 > 256
Cert Sig: ECDSA > RSA

Modern: strongest ciphers (PFS-only) & latest TLS version(s) Default: mix of various strength ciphers & recent TLS versions Strict: deprecated, Default plus ECDHE+RSA+AES{128,256}+CBC+SHA1 for IE 11 Legacy: many ciphers & TLS versions for maximum compatibility, less secure SFAllowed: provides only the ciphers allowed according to SFSS-151.

Index

• Constants
• Variables
• func Default(config *tls.Config)
• func DefaultCommonRuntime(config *tls.Config)
• func Legacy(config *tls.Config)
• func Modern(config *tls.Config)
• func New() *tls.Config
• func NewMutualTLS(caCerts [][]byte, serverCert tls.Certificate) (*tls.Config, error)
• func PoolFromPEM(cert []byte) (*x509.CertPool, error)
• func SFAllowed(config *tls.Config)
• func Strict(config *tls.Config)
• type CA
  • func LoadCA(certPEM, keyPEM []byte, chainPEMs ...[]byte) (*CA, error)
  • func (c *CA) NewLeaf(config LeafConfig) (*tls.Certificate, error)
• type LeafConfig

Constants

const (
	InstanceIdentityDocID int = iota
	InstanceIdentitySigID
)

Variables

var (
	// DefaultCiphers provides strong security for a wide range of clients.
	DefaultCiphers = []uint16{
		tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
		tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
		tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
		tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
		tls.TLS_RSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_RSA_WITH_AES_128_CBC_SHA256,
		tls.TLS_RSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
		tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
	}

	// LegacyCiphers supports a maximum number of old devices.
	//
	// See https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility
	LegacyCiphers = []uint16{
		tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
		tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
		tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
		tls.TLS_RSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_RSA_WITH_AES_128_CBC_SHA256,
		tls.TLS_RSA_WITH_AES_128_CBC_SHA,
		tls.TLS_RSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_RSA_WITH_AES_256_CBC_SHA,
		tls.TLS_RSA_WITH_3DES_EDE_CBC_SHA,
	}

	// ModernCiphers provides the highest level of security for modern devices.
	ModernCiphers = []uint16{
		tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
		tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
		tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
		tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
	}

	// SFCiphers provides the ciphers allowed by and ordered according to SFSS-151.
	// See https://help.salesforce.com/articleView?id=000351980
	// We do not support CBC ciphers because of Golang choosing to not address CBC issues mitigated by newer clients
	SFCiphers = []uint16{
		tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
		tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
		tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_RSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_RSA_WITH_AES_128_GCM_SHA256,
	}

	// StrictCiphers balences high level of security with backwards compatibility.
	StrictCiphers = []uint16{
		tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
		tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
		tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
		tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
		tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
		tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
		tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
		tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
	}
)

var (
	InstanceIdentityDocOID asn1.ObjectIdentifier = append(oidPrefix, InstanceIdentityDocID)
	InstanceIdentitySigOID asn1.ObjectIdentifier = append(oidPrefix, InstanceIdentitySigID)
)

var ErrCannotAppendFromPEM = errors.New("cannot append from PEM")

Functions

func Default

func Default(config *tls.Config)

Default modifies config with safe defaults for standard compatibility.

func DefaultCommonRuntime

func DefaultCommonRuntime(config *tls.Config)

DefaultCommonRuntime modifies config with safe defaults for standard compatibility. This is different from Default because the common runtime supports TLS 1.0 until July 31, 2021

func Legacy

func Legacy(config *tls.Config)

Legacy modifies config with safe defaults for backwards compatibility.

func Modern

func Modern(config *tls.Config)

Modern modifies config with safe defaults for modern browser compatibility.

func New

func New() *tls.Config

New returns a TLS configuration tuned for performance and security based on the recommendations in: https://blog.gopheracademy.com/advent-2016/exposing-go-on-the-internet/

AES128 & SHA256 preferred over AES256 & SHA384: https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices#31-avoid-too-much-security

func NewMutualTLS

func NewMutualTLS(caCerts [][]byte, serverCert tls.Certificate) (*tls.Config, error)

NewMutualTLS returns a TLS configuration setup for mutual TLS authentication.

func PoolFromPEM

func PoolFromPEM(cert []byte) (*x509.CertPool, error)

PoolFromPEM accepts a RootCA PEM in the form of a byte slice and returns a cert pool.

func SFAllowed

func SFAllowed(config *tls.Config)

SFAllowed modifies config for compliance with the salesforce policy.

func Strict

func Strict(config *tls.Config)

Strict modifies config with safe defaults for compliance compatibility.

Types

type CA

type CA tls.Certificate

CA is a certificate & key that generate new signed leaf TLS Certificates.

func LoadCA

func LoadCA(certPEM, keyPEM []byte, chainPEMs ...[]byte) (*CA, error)

LoadCA initializes a TLS certificate and key, along with an optional certificate chain from raw PEM encoded values.

func (*CA) NewLeaf

func (c *CA) NewLeaf(config LeafConfig) (*tls.Certificate, error)

NewLeaf generates a new leaf certificate & key signed by c.

type LeafConfig

type LeafConfig struct {
	// Hostname is used for the subject CN and DNSNames fields. Ignored if CSR is present.
	Hostname string
	// CSR is the x509 certificate request.
	CSR *x509.CertificateRequest
	// IID is the EC2 Instance Identity Document data and signature.
	IID *identitydoc.InstanceIdentityDocument
	// PublicKeyAlgorithm is the type of public key generated for the certificate.
	PublicKeyAlgorithm x509.PublicKeyAlgorithm
}