types

README

Consul types Package

The Go language has a strong type system built into the language. The types package corrals named types into a single package that is terminal in go's import graph. The types package should not have any downstream dependencies. Each subsystem that defines its own set of types exists in its own file, but all types are defined in the same package.

Why

Everything should be made as simple as possible, but not simpler.

string is a useful container and underlying type for identifiers, however the string type is effectively opaque to the compiler in terms of how a given string is intended to be used. For instance, there is nothing preventing the following from happening:

// `map` of Widgets, looked up by ID
var widgetLookup map[string]*Widget
// ...
var widgetID string = "widgetID"
w, found := widgetLookup[widgetID]

// Bad!
var widgetName string = "name of widget"
w, found := widgetLookup[widgetName]

but this class of problem is entirely preventable:

type WidgetID string
var widgetLookup map[WidgetID]*Widget
var widgetName

TL;DR: intentions and idioms aren't statically checked by compilers. The types package uses Go's strong type system to prevent this class of bug.

Documentation

Index

• Constants
• Variables
• func MarshalEnvoyTLSCipherSuiteStrings(cipherSuites []TLSCipherSuite) []string
• func ValidateConsulAgentCipherSuites(cipherSuites []TLSCipherSuite) error
• func ValidateEnvoyCipherSuites(cipherSuites []TLSCipherSuite) error
• func ValidateTLSVersion(v TLSVersion) error
• type AreaID
• type CheckID
• type NodeID
• type TLSCipherSuite
  • func (c *TLSCipherSuite) String() string
• type TLSVersion
  • func (a TLSVersion) LessThan(b TLSVersion) (error, bool)
  • func (v *TLSVersion) String() string

Constants

const (
	// Cipher suites used by both Envoy and Consul agent
	TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 = "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256"
	TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256   = "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256"
	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256       = "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256         = "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA          = "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA"
	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA            = "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA"
	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384       = "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"
	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384         = "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA          = "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA"
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA            = "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA"

	// Older cipher suites not supported for Consul agent TLS,
	// will eventually be removed from Envoy defaults
	TLS_RSA_WITH_AES_128_GCM_SHA256 = "TLS_RSA_WITH_AES_128_GCM_SHA256"
	TLS_RSA_WITH_AES_128_CBC_SHA    = "TLS_RSA_WITH_AES_128_CBC_SHA"
	TLS_RSA_WITH_AES_256_GCM_SHA384 = "TLS_RSA_WITH_AES_256_GCM_SHA384"
	TLS_RSA_WITH_AES_256_CBC_SHA    = "TLS_RSA_WITH_AES_256_CBC_SHA"
)

Variables

var (

	// NOTE: This interface is deprecated in favor of tlsVersions
	// and should be eventually removed in a future release.
	DeprecatedConsulAgentTLSVersions = map[string]TLSVersion{
		"":      TLSVersionAuto,
		"tls10": TLSv1_0,
		"tls11": TLSv1_1,
		"tls12": TLSv1_2,
		"tls13": TLSv1_3,
	}
	// NOTE: these currently map to the deprecated config strings to support the
	// deployment pattern of upgrading servers first. This map should eventually
	// be removed and any lookups updated to instead use the TLSVersion string
	// values directly in a future release.
	ConsulAutoConfigTLSVersionStrings = map[TLSVersion]string{
		TLSVersionAuto: "",
		TLSv1_0:        "tls10",
		TLSv1_1:        "tls11",
		TLSv1_2:        "tls12",
		TLSv1_3:        "tls13",
	}
	TLSVersionsWithConfigurableCipherSuites = map[TLSVersion]struct{}{

		TLSVersionUnspecified: {},
		TLSVersionAuto:        {},

		TLSv1_0: {},
		TLSv1_1: {},
		TLSv1_2: {},
	}
)

Functions

func MarshalEnvoyTLSCipherSuiteStrings

func MarshalEnvoyTLSCipherSuiteStrings(cipherSuites []TLSCipherSuite) []string

func ValidateConsulAgentCipherSuites

func ValidateConsulAgentCipherSuites(cipherSuites []TLSCipherSuite) error

func ValidateEnvoyCipherSuites

func ValidateEnvoyCipherSuites(cipherSuites []TLSCipherSuite) error

func ValidateTLSVersion

func ValidateTLSVersion(v TLSVersion) error

Types

type AreaID

type AreaID string

AreaID is a strongly-typed string used to uniquely represent a network area, which is a relationship between Consul servers.

const AreaLAN AreaID = "lan"

This represents the existing LAN area that's built in to Consul. Consul Enterprise generalizes areas, which are represented with UUIDs.

const AreaWAN AreaID = "wan"

This represents the existing WAN area that's built in to Consul. Consul Enterprise generalizes areas, which are represented with UUIDs.

type CheckID

type CheckID string

CheckID is a strongly typed string used to uniquely represent a Consul Check on an Agent (a CheckID is not globally unique).

type NodeID

type NodeID string

NodeID is a unique identifier for a node across space and time.

type TLSCipherSuite

type TLSCipherSuite string

IANA cipher suite string constants as defined at https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml This is the total list of TLS 1.2-style cipher suites which are currently supported by either Envoy 1.21 or the Consul agent via Go, and may change as some older suites are removed in future Envoy releases and Consul drops support for older Envoy versions, and as supported cipher suites in the Go runtime change.

The naming convention for cipher suites changed in TLS 1.3 but constant values should still be globally unqiue.

Handling validation on distinct sets of TLS 1.3 and TLS 1.2 TLSCipherSuite constants would be a future exercise if cipher suites for TLS 1.3 ever become configurable in BoringSSL, Envoy, or other implementation.

func (*TLSCipherSuite) String

func (c *TLSCipherSuite) String() string

type TLSVersion

type TLSVersion string

TLSVersion is a strongly-typed string for TLS versions

const (
	// Error value, excluded from lookup maps
	TLSVersionInvalid TLSVersion = "TLS_INVALID"

	// Explicit unspecified zero-value to avoid overwriting parent defaults
	TLSVersionUnspecified TLSVersion = ""

	// Explictly allow implementation to select TLS version
	// May be useful to supercede defaults specified at a higher layer
	TLSVersionAuto TLSVersion = "TLS_AUTO"

	// TLS versions
	TLSv1_0 TLSVersion = "TLSv1_0"
	TLSv1_1 TLSVersion = "TLSv1_1"
	TLSv1_2 TLSVersion = "TLSv1_2"
	TLSv1_3 TLSVersion = "TLSv1_3"
)

func (TLSVersion) LessThan

func (a TLSVersion) LessThan(b TLSVersion) (error, bool)

Will only return true for concrete versions and won't catch implementation-dependent conflicts with TLSVersionAuto or unspecified values

func (*TLSVersion) String

func (v *TLSVersion) String() string