configtls

README

TLS Configuration Settings

Crypto TLS exposes a variety of settings. Several of these settings are available for configuration within individual receivers or exporters.

Note that mutual TLS (mTLS) is also supported as an optional enhancement on top of standard TLS.

TLS / mTLS Configuration

By default, TLS is enabled with server certificate verification using the system root CAs. No additional configuration is needed for standard TLS. Mutual TLS (mTLS), where both client and server present certificates, is optional and requires additional configuration (see examples below).

• insecure (default = false): whether to disable transport security entirely. When set to true, no TLS is used at all. See grpc.WithInsecure() for gRPC.
• curve_preferences (default = []): specify your curve preferences that will be used in an ECDHE handshake, in preference order. Accepted values are:
  • X25519
  • P521
  • P256
  • P384

The following certificate parameters can be configured:

• ca_file: Path to the CA cert. For a client this verifies the server certificate. For a server this verifies client certificates. If empty, the system root CAs are used.

  • ca_pem: Alternative to ca_file. Provide the CA cert contents as a string instead of a filepath.

• cert_file: Path to the TLS certificate. For a server this is required to serve TLS. For a client this is only needed for mTLS (client certificate authentication).

  • cert_pem: Alternative to cert_file. Provide the certificate contents as a string instead of a filepath.

• key_file: Path to the TLS private key. Must be provided alongside cert_file.

  • key_pem: Alternative to key_file. Provide the key contents as a string instead of a filepath.

You can also combine defining a certificate authority with the system certificate authorities.

• include_system_ca_certs_pool (default = false): whether to load the system certificate authorities pool alongside the certificate authority.

Additionally you can configure TLS to be enabled but skip verifying the server's certificate chain. This cannot be combined with insecure since insecure won't use TLS at all.

• insecure_skip_verify (default = false): whether to skip verifying the certificate or not.

Minimum and maximum TLS version can be set:

IMPORTANT: TLS 1.0 and 1.1 are deprecated due to known vulnerabilities and should be avoided.

• min_version (default = "1.2"): Minimum acceptable TLS version.

  • options: ["1.0", "1.1", "1.2", "1.3"]

• max_version (default = "" handled by crypto/tls - currently TLS 1.3): Maximum acceptable TLS version.

  • options: ["1.0", "1.1", "1.2", "1.3"]

Explicit cipher suites can be set. If left blank, a safe default list is used. See https://go.dev/src/crypto/tls/cipher_suites.go for a list of supported cipher suites.

• cipher_suites: (default = []): List of cipher suites to use.

Example:

  cipher_suites:
    - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
    - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

Additionally certificates may be reloaded by setting the below configuration.

• reload_interval (optional) : ReloadInterval specifies the duration after which the certificate will be reloaded. If not set, it will never be reloaded. Accepts a duration string, valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

How TLS/mTLS is configured depends on whether configuring the client or server. See below for examples.

• tpm (optional): Use the trusted platform module to retrieve the TLS key.

Insecure Cipher Suites

WARNING: Insecure cipher suites can be enabled for legacy system compatibility but this should be used with extreme caution as it may expose your system to security vulnerabilities.

• include_insecure_cipher_suites: (default = false): Whether to include insecure cipher suites returned by tls.InsecureCipherSuites() in addition to the secure ones

Example:

  cipher_suites:
    - TLS_RSA_WITH_RC4_128_SHA
    - TLS_RSA_WITH_3DES_EDE_CBC_SHA
  include_insecure_cipher_suites: true

Client Configuration

Exporters leverage client configuration. The TLS configuration parameters are defined under tls, like server configuration.

Beyond TLS configuration, the following setting can optionally be configured:

• server_name_override: If set to a non-empty string, it will override the virtual host name of authority (e.g. :authority header field) in requests (typically used for testing).

Example:

exporters:
  otlp_grpc:
    endpoint: myserver.local:55690
    tls:
      insecure: false
      ca_file: server.crt
      cert_file: client.crt
      key_file: client.key
      min_version: "1.1"
      max_version: "1.2"
  otlp/insecure:
    endpoint: myserver.local:55690
    tls:
      insecure: true
  otlp/secure_no_verify:
    endpoint: myserver.local:55690
    tls:
      insecure: false
      insecure_skip_verify: true

Server Configuration

Receivers leverage server configuration.

Beyond TLS configuration, the following setting can optionally be configured (required for mTLS):

• client_ca_file: Path to the TLS cert to use by the server to verify a client certificate. (optional) This sets the ClientCAs and ClientAuth to RequireAndVerifyClientCert in the TLSConfig. Please refer to https://godoc.org/crypto/tls#Config for more information.
• client_ca_file_reload (default = false): Reload the ClientCAs file when it is modified.

Example:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: mysite.local:55690
        tls:
          cert_file: server.crt
          key_file: server.key
  otlp/mtls:
    protocols:
      grpc:
        endpoint: mysite.local:55690
        tls:
          client_ca_file: client.pem
          cert_file: server.crt
          key_file: server.key
  otlp/notls:
    protocols:
      grpc:
        endpoint: mysite.local:55690

Trusted platform module (TPM) configuration

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

• enabled (default = false): Enables loading tls.key_file from TPM.

• path (default = ""): The path to the TPM device or Unix domain socket. For instance /dev/tpm0 or /dev/tpmrm0. This option is not supported on Windows.

• owner_auth (default = ""): The owner authorization value. This is used to authenticate the TPM device. If not set, the default owner authorization will be used.

• auth (default = ""): The authorization value. This is used to authenticate the TPM device. If not set, the default authorization will be used.

Example:

exporters:
  otlp_grpc:
    endpoint: myserver.local:55690
    tls:
      ca_file: ca.crt
      cert_file: client.crt
      key_file: client-tss2.key
      tpm:
        enabled: true
        path: /dev/tpmrm0

The client-tss2.key private key with TSS2 format will be loaded from the TPM device /dev/tpmrm0.

Documentation

Overview

Package configtls implements the TLS settings to load and configure TLS clients and servers.

Index

• type ClientConfig
  • func NewDefaultClientConfig() ClientConfig
  • func (c ClientConfig) LoadTLSConfig(_ context.Context) (*tls.Config, error)
• type Config
  • func NewDefaultConfig() Config
  • func (c Config) Validate() error
• type ServerConfig
  • func NewDefaultServerConfig() ServerConfig
  • func (c ServerConfig) LoadTLSConfig(_ context.Context) (*tls.Config, error)
  • func (c ServerConfig) Validate() error
• type TPMConfig

Types

type ClientConfig

type ClientConfig struct {
	// squash ensures fields are correctly decoded in embedded struct.
	Config `mapstructure:",squash"`

	// In gRPC and HTTP when set to true, this is used to disable the client transport security.
	// See https://godoc.org/google.golang.org/grpc#WithInsecure for gRPC.
	// Please refer to https://godoc.org/crypto/tls#Config for more information.
	// (optional, default false)
	Insecure bool `mapstructure:"insecure,omitempty"`
	// InsecureSkipVerify will enable TLS but not verify the certificate.
	InsecureSkipVerify bool `mapstructure:"insecure_skip_verify,omitempty"`
	// ServerName requested by client for virtual hosting.
	// This sets the ServerName in the TLSConfig. Please refer to
	// https://godoc.org/crypto/tls#Config for more information. (optional)
	ServerName string `mapstructure:"server_name_override,omitempty"`
	// contains filtered or unexported fields
}

ClientConfig contains TLS configurations that are specific to client connections in addition to the common configurations. This should be used by components configuring TLS client connections.

func NewDefaultClientConfig

func NewDefaultClientConfig() ClientConfig

NewDefaultClientConfig creates a new ClientConfig with any default values set.

func (ClientConfig) LoadTLSConfig

func (c ClientConfig) LoadTLSConfig(_ context.Context) (*tls.Config, error)

LoadTLSConfig loads the TLS configuration.

type Config

type Config struct {
	// Path to the CA cert. For a client this verifies the server certificate.
	// For a server this verifies client certificates. If empty uses system root CA.
	// (optional)
	CAFile string `mapstructure:"ca_file,omitempty"`

	// In memory PEM encoded cert. (optional)
	CAPem configopaque.String `mapstructure:"ca_pem,omitempty"`

	// If true, load system CA certificates pool in addition to the certificates
	// configured in this struct.
	IncludeSystemCACertsPool bool `mapstructure:"include_system_ca_certs_pool,omitempty"`

	// Path to the TLS cert to use for TLS required connections. (optional)
	CertFile string `mapstructure:"cert_file,omitempty"`

	// In memory PEM encoded TLS cert to use for TLS required connections. (optional)
	CertPem configopaque.String `mapstructure:"cert_pem,omitempty"`

	// Path to the TLS key to use for TLS required connections. (optional)
	KeyFile string `mapstructure:"key_file,omitempty"`

	// In memory PEM encoded TLS key to use for TLS required connections. (optional)
	KeyPem configopaque.String `mapstructure:"key_pem,omitempty"`

	// MinVersion sets the minimum TLS version that is acceptable.
	// If not set, TLS 1.2 will be used. (optional)
	MinVersion string `mapstructure:"min_version,omitempty"`

	// MaxVersion sets the maximum TLS version that is acceptable.
	// If not set, refer to crypto/tls for defaults. (optional)
	MaxVersion string `mapstructure:"max_version,omitempty"`

	// CipherSuites is a list of TLS cipher suites that the TLS transport can use.
	// If left blank, a safe default list is used.
	// See https://go.dev/src/crypto/tls/cipher_suites.go for a list of supported cipher suites.
	CipherSuites []string `mapstructure:"cipher_suites,omitempty"`

	// IncludeInsecureCipherSuites enables support for insecure cipher suites.
	// When set to true, cipher suites returned by tls.InsecureCipherSuites() will be
	// available for selection in addition to the secure ones. This should only be
	// used when working with legacy systems that require insecure cipher suites.
	// (optional, default false)
	IncludeInsecureCipherSuites bool `mapstructure:"include_insecure_cipher_suites,omitempty"`

	// ReloadInterval specifies the duration after which the certificate will be reloaded
	// If not set, it will never be reloaded (optional)
	ReloadInterval time.Duration `mapstructure:"reload_interval,omitempty"`

	// contains the elliptic curves that will be used in
	// an ECDHE handshake, in preference order
	// Defaults to empty list and "crypto/tls" defaults are used, internally.
	CurvePreferences []string `mapstructure:"curve_preferences,omitempty"`

	// Trusted platform module configuration
	TPMConfig TPMConfig `mapstructure:"tpm,omitempty"`
}

Config exposes the common client and server TLS configurations. Note: Since there isn't anything specific to a server connection. Components with server connections should use Config.

func NewDefaultConfig

func NewDefaultConfig() Config

NewDefaultConfig creates a new Config with any default values set.

func (Config) Validate

func (c Config) Validate() error

type ServerConfig

type ServerConfig struct {
	// squash ensures fields are correctly decoded in embedded struct.
	Config `mapstructure:",squash"`

	// Path to the TLS cert to use by the server to verify a client certificate. (optional)
	// This sets the ClientCAs and ClientAuth to RequireAndVerifyClientCert in the TLSConfig. Please refer to
	// https://godoc.org/crypto/tls#Config for more information. (optional)
	ClientCAFile string `mapstructure:"client_ca_file,omitempty"`

	// Reload the ClientCAs file when it is modified
	// (optional, default false)
	ReloadClientCAFile bool `mapstructure:"client_ca_file_reload,omitempty"`
	// contains filtered or unexported fields
}

ServerConfig contains TLS configurations that are specific to server connections in addition to the common configurations. This should be used by components configuring TLS server connections.

func NewDefaultServerConfig

func NewDefaultServerConfig() ServerConfig

NewDefaultServerConfig creates a new ServerConfig with any default values set.

func (ServerConfig) LoadTLSConfig

func (c ServerConfig) LoadTLSConfig(_ context.Context) (*tls.Config, error)

LoadTLSConfig loads the TLS configuration.

func (ServerConfig) Validate

func (c ServerConfig) Validate() error

type TPMConfig

type TPMConfig struct {
	Enabled bool `mapstructure:"enabled"`
	// The path to the TPM device or Unix domain socket.
	// For instance /dev/tpm0 or /dev/tpmrm0.
	Path      string `mapstructure:"path"`
	OwnerAuth string `mapstructure:"owner_auth"`
	Auth      string `mapstructure:"auth"`
	// contains filtered or unexported fields
}

TPMConfig defines trusted platform module configuration for storing TLS keys.