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.

TLS / mTLS Configuration

By default, TLS is enabled:

• insecure (default = false): whether to enable client transport security for the exporter's gRPC connection. See grpc.WithInsecure().

As a result, the following parameters are also required:

• cert_file: Path to the TLS cert to use for TLS required connections. Should only be used if insecure is set to false.
• key_file: Path to the TLS key to use for TLS required connections. Should only be used if insecure is set to false.

A certificate authority may also need to be defined:

• ca_file: 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. Should only be used if insecure is set to false.

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

Additionally certifaces 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.

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

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:
    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.

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

Documentation

Overview

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

Index

• type TLSClientSetting
  • func (c TLSClientSetting) LoadTLSConfig() (*tls.Config, error)
• type TLSServerSetting
  • func (c TLSServerSetting) LoadTLSConfig() (*tls.Config, error)
• type TLSSetting

Types

type TLSClientSetting

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

	// In gRPC when set to true, this is used to disable the client transport security.
	// See https://godoc.org/google.golang.org/grpc#WithInsecure.
	// In HTTP, this disables verifying the server's certificate chain and host name
	// (InsecureSkipVerify in the tls Config). Please refer to
	// https://godoc.org/crypto/tls#Config for more information.
	// (optional, default false)
	Insecure bool `mapstructure:"insecure"`
	// InsecureSkipVerify will enable TLS but not verify the certificate.
	InsecureSkipVerify bool `mapstructure:"insecure_skip_verify"`
	// 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"`
}

TLSClientSetting 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 (TLSClientSetting) LoadTLSConfig

func (c TLSClientSetting) LoadTLSConfig() (*tls.Config, error)

LoadTLSConfig loads the TLS configuration.

type TLSServerSetting

type TLSServerSetting struct {
	// squash ensures fields are correctly decoded in embedded struct.
	TLSSetting `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"`
}

TLSServerSetting 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 (TLSServerSetting) LoadTLSConfig

func (c TLSServerSetting) LoadTLSConfig() (*tls.Config, error)

LoadTLSConfig loads the TLS configuration.

type TLSSetting

type TLSSetting 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"`

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

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

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

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

	// 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"`
}

TLSSetting 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 TLSSetting.