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
• type AreaID
• type CheckID
• type NodeID
• type TLSCipherSuite
• type TLSVersion
  • func (v TLSVersion) MarshalJSON() ([]byte, error)
  • func (v TLSVersion) String() string
  • func (v *TLSVersion) UnmarshalJSON(bytes []byte) error

Constants

const (
	// Envoy cipher suites also used by Consul agent
	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256       TLSCipherSuite = 0xc02b
	TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256                = 0xcca9 // Not used by Consul agent yet
	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256                        = 0xc02f
	TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256                  = 0xcca8 // Not used by Consul agent yet
	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA                         = 0xc009
	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA                           = 0xc013
	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384                      = 0xc02c
	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384                        = 0xc030
	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA                         = 0xc00a
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA                           = 0xc014

	// Older cipher suites not supported for Consul agent TLS, will eventually be removed from Envoy defaults
	TLS_RSA_WITH_AES_128_GCM_SHA256 = 0x009c
	TLS_RSA_WITH_AES_128_CBC_SHA    = 0x002f
	TLS_RSA_WITH_AES_256_GCM_SHA384 = 0x009d
	TLS_RSA_WITH_AES_256_CBC_SHA    = 0x0035

	// Additional cipher suites used by Consul agent but not Envoy
	// TODO: these are both explicitly listed as insecure and disabled in the Go source, should they be removed?
	// https://cs.opensource.google/go/go/+/refs/tags/go1.17.3:src/crypto/tls/cipher_suites.go;l=329-330
	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 = 0x0023
	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256   = 0xc027
)

Variables

var (
	TLSVersions = map[string]TLSVersion{
		"TLS_AUTO": TLSVersionAuto,
		"TLSv1_0":  TLSv1_0,
		"TLSv1_1":  TLSv1_1,
		"TLSv1_2":  TLSv1_2,
		"TLSv1_3":  TLSv1_3,
	}
	// 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,
	}
	HumanTLSVersionStrings = map[TLSVersion]string{
		TLSVersionAuto: "Allow implementation to select TLS version",
		TLSv1_0:        "TLS 1.0",
		TLSv1_1:        "TLS 1.1",
		TLSv1_2:        "TLS 1.2",
		TLSv1_3:        "TLS 1.3",
	}
	ConsulConfigTLSVersionStrings = func() map[TLSVersion]string {
		inverted := make(map[TLSVersion]string, len(TLSVersions))
		for k, v := range TLSVersions {
			inverted[v] = k
		}
		return inverted
	}()
	// 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 use ConsulConfigTLSVersionStrings
	// with newer config strings instead in a future release.
	ConsulAutoConfigTLSVersionStrings = map[TLSVersion]string{
		TLSVersionAuto: "",
		TLSv1_0:        "tls10",
		TLSv1_1:        "tls11",
		TLSv1_2:        "tls12",
		TLSv1_3:        "tls13",
	}
)

var (
	TLSCipherSuites = map[string]TLSCipherSuite{
		"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256": TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
		"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA":          TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,
		"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256":       TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
		"TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA":          TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,
		"TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384":       TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
		"TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256":   TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
		"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA":            TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
		"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256":         TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
		"TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA":            TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
		"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384":         TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,

		"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,

		"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256": TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
		"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256":   TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
	}
	HumanTLSCipherSuiteStrings = func() map[TLSCipherSuite]string {
		inverted := make(map[TLSCipherSuite]string, len(TLSCipherSuites))
		for k, v := range TLSCipherSuites {
			inverted[v] = k
		}
		return inverted
	}()
	EnvoyTLSCipherSuiteStrings = map[TLSCipherSuite]string{
		TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256:       "ECDHE-ECDSA-AES128-GCM-SHA256",
		TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256: "ECDHE-ECDSA-CHACHA20-POLY1305",
		TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256:         "ECDHE-RSA-AES128-GCM-SHA256",
		TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:   "ECDHE-RSA-CHACHA20-POLY1305",
		TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA:          "ECDHE-ECDSA-AES128-SHA",
		TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA:            "ECDHE-RSA-AES128-SHA",
		TLS_RSA_WITH_AES_128_GCM_SHA256:               "AES128-GCM-SHA256",
		TLS_RSA_WITH_AES_128_CBC_SHA:                  "AES128-SHA",
		TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384:       "ECDHE-ECDSA-AES256-GCM-SHA384",
		TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:         "ECDHE-RSA-AES256-GCM-SHA384",
		TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA:          "ECDHE-ECDSA-AES256-SHA",
		TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA:            "ECDHE-RSA-AES256-SHA",
		TLS_RSA_WITH_AES_256_GCM_SHA384:               "AES256-GCM-SHA384",
		TLS_RSA_WITH_AES_256_CBC_SHA:                  "AES256-SHA",
	}
)

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 uint16

IANA cipher suite constants and values 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 a subset of TLSCipherSuite constants would be a future exercise if cipher suites for TLS 1.3 ever become configurable in BoringSSL, Envoy, or other implementation

type TLSVersion

type TLSVersion int

TLSVersion is a strongly-typed int used for relative comparison (minimum, maximum, greater than, less than) of TLS versions

const (
	// Error value, excluded from lookup maps
	TLSVersionInvalid TLSVersion = iota - 1

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

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

	// TLS versions
	TLSv1_0
	TLSv1_1
	TLSv1_2
	TLSv1_3
)

func (TLSVersion) MarshalJSON

func (v TLSVersion) MarshalJSON() ([]byte, error)

func (TLSVersion) String

func (v TLSVersion) String() string

func (*TLSVersion) UnmarshalJSON

func (v *TLSVersion) UnmarshalJSON(bytes []byte) error