Documentation
¶
Overview ¶
Package tls configures TLS for LabKit servers, including verification of client certificates.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrIncompleteKeyPair = errors.New("incomplete tls key pair")
ErrIncompleteKeyPair is returned when a serving certificate is configured without its private key, or a private key without its certificate.
var ErrInvalidCipherSuite = errors.New("invalid tls cipher suite")
ErrInvalidCipherSuite is returned when a cipher suite is configured that this package cannot serve.
var ErrInvalidClientAuth = errors.New("invalid tls client authentication")
ErrInvalidClientAuth is returned when client authentication is configured in a way this package cannot serve.
var ErrInvalidVersion = errors.New("invalid tls version")
ErrInvalidVersion is returned when the configured TLS protocol versions cannot be served.
var ErrMissingClientCA = errors.New("no client certificate authority configured")
ErrMissingClientCA is returned when a client authentication mode that verifies certificates is configured without any authority to verify against. This is refused rather than defaulted because a nil crypto/tls ClientCAs falls back to the host's trust store, which would admit any clientAuth certificate from any public authority.
var ErrNoCertificate = errors.New("no tls serving certificate configured")
ErrNoCertificate is returned when TLS is enabled but no serving certificate is configured.
var ErrNoCipherSuite = errors.New("no usable tls cipher suite configured")
ErrNoCipherSuite is returned when no configured cipher suite can serve a protocol version the server negotiates, which would fail every handshake at that version.
Functions ¶
This section is empty.
Types ¶
type CipherSuite ¶
type CipherSuite string
CipherSuite names a TLS cipher suite, spelled as crypto/tls spells it.
func (*CipherSuite) UnmarshalText ¶
func (s *CipherSuite) UnmarshalText(text []byte) error
UnmarshalText implements encoding.TextUnmarshaler, so a CipherSuite can be decoded straight out of JSON, YAML or an environment variable without the consumer writing an adapter. The receiver is left unchanged when the input does not parse.
type ClientAuthMode ¶
type ClientAuthMode string
ClientAuthMode selects how a server treats a client certificate. The values are nginx's ssl_verify_client vocabulary, so a Helm chart value and a LabKit value are the same string.
const ( // ClientAuthUnset leaves the mode to be resolved from the rest of the // configuration. It is the zero value. ClientAuthUnset ClientAuthMode = "" // ClientAuthOff neither requests nor accepts a client certificate. ClientAuthOff ClientAuthMode = "off" // ClientAuthOptionalNoCA requests a client certificate and admits the // client whatever it presents, without verifying it. The certificate is // available to the application, which takes on the whole of the // verification burden. ClientAuthOptionalNoCA ClientAuthMode = "optional_no_ca" // ClientAuthOptional verifies a client certificate against the configured // certificate authorities when one is presented, and admits a client that // presents none. ClientAuthOptional ClientAuthMode = "optional" // ClientAuthOn requires every client to present a certificate that // verifies against the configured certificate authorities. ClientAuthOn ClientAuthMode = "on" )
func (ClientAuthMode) String ¶
func (m ClientAuthMode) String() string
String implements fmt.Stringer. The zero value renders as "unset" so it is distinguishable in a log line.
func (*ClientAuthMode) UnmarshalText ¶
func (m *ClientAuthMode) UnmarshalText(text []byte) error
UnmarshalText implements encoding.TextUnmarshaler, so a ClientAuthMode can be decoded straight out of JSON, YAML or an environment variable without the consumer writing an adapter. The receiver is left unchanged when the input does not parse.
type Config ¶
type Config struct {
// Name identifies this configuration in errors and log lines. Defaults to
// "tls". Give distinct names to distinct listeners.
Name string
// Enabled turns TLS on. It defaults to false and is never inferred from
// the presence of certificate material, mirroring tls.enabled in the
// GitLab Helm charts. A disabled configuration that carries material is
// reported, and serves plaintext.
Enabled bool
// CertFile is the path to the PEM-encoded serving certificate. It may hold
// a chain, leaf first, when clients need intermediates to reach a trusted
// root. In a Kubernetes deployment it is the tls.crt entry of a
// kubernetes.io/tls secret, mounted as a file.
//
// The certificate must carry the names its clients dial as subject
// alternative names; a common name alone is not accepted.
//
// The path is trimmed, and a blank value counts as absent.
CertFile string
// KeyFile is the path to the PEM-encoded private key for CertFile. In a
// Kubernetes deployment it is the tls.key entry of the same secret.
//
// The path is trimmed, and a blank value counts as absent.
KeyFile string
// ClientCAFiles are paths to PEM-encoded certificate authorities that
// client certificates are verified against. A file may hold a bundle, and
// every certificate in every file is trusted. In a Kubernetes deployment
// this is the ca.crt entry of a trust-manager Bundle or an Opaque secret,
// mounted as a file.
//
// Paths are trimmed, and a blank entry is ignored.
//
// Configuring authorities does not by itself require a client to present a
// certificate. See ClientAuth.
ClientCAFiles []string
// ClientAuth selects how a client certificate is treated. The zero value
// resolves against ClientCAFiles: ClientAuthOptional when authorities are
// configured, ClientAuthOff when they are not.
ClientAuth ClientAuthMode
// MinVersion is the oldest protocol version the server will negotiate. The
// zero value resolves to VersionTLS12.
MinVersion Version
// MaxVersion is the newest protocol version the server will negotiate. The
// zero value imposes no maximum.
MaxVersion Version
// CipherSuites are the cipher suites the server will negotiate for TLS 1.2,
// spelled as crypto/tls spells them and matched case-insensitively. The
// zero value leaves the choice to crypto/tls. TLS 1.3 cipher suites are not
// configurable, so naming one here does not select it.
CipherSuites []CipherSuite
// Logger receives the log lines this configuration emits as it resolves.
// When nil, nothing is logged.
Logger *slog.Logger
}
Config describes how a server serves TLS. The zero value serves plaintext, so a consumer can wire TLS unconditionally and leave the decision to configuration.
type Version ¶
type Version string
Version names a TLS protocol version.
func (Version) String ¶
String implements fmt.Stringer. The zero value renders as "unset" so it is distinguishable in a log line.
func (*Version) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler, so a Version can be decoded straight out of JSON, YAML or an environment variable without the consumer writing an adapter. The receiver is left unchanged when the input does not parse.
Source Files