mtls

package
v0.0.0-...-c88e5ae Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 37 Imported by: 0

Documentation

Overview

Package mtls terminates mutual TLS on a service's existing port, in a mode that can change at runtime, with plaintext and TLS side by side until a listener is told otherwise.

Attach points

A gRPC server built with the shared constructor takes ServerCredentials through its WithTransportCredentials option and the two interceptors through WithUnaryInterceptors and WithStreamInterceptors:

cfg := mtls.ServerConfig{Name: "grpc-internal", Files: files, Mode: mode, Allow: allow}
server := e2bgrpc.NewGRPCServer(tel,
	e2bgrpc.WithTransportCredentials(mtls.NewServerCredentials(cfg)),
	e2bgrpc.WithUnaryInterceptors(mtls.UnaryServerInterceptor(cfg)),
	e2bgrpc.WithStreamInterceptors(mtls.StreamServerInterceptor(cfg)))

An HTTP server is served through Listener, with HTTPGuard wrapped around the application handler, so every request, each HTTP/2 stream included, passes the guard. The guard takes the listener's ConnState, which carries each connection's chain verdict, something r.TLS cannot tell it; without it a required listener treats every TLS request as unverified:

l := mtls.NewListener(inner, cfg)
server.Handler = mtls.NewHTTPGuard(cfg, []string{"/health"}, app, mtls.WithGuardConnStateLookup(l.ConnState))
httpserver.ConfigureH2C(server)
err := server.Serve(l)

Both attach points read the first byte of a connection: 0x16 starts a TLS handshake, anything else is plaintext. The gRPC branch negotiates ALPN h2, as grpc-go requires; the HTTP branch offers http/1.1 by default and hands the *tls.Conn to net/http unwrapped so r.TLS is populated. Classification and the handshake share one deadline, DefaultHandshakeTimeout, so a silent or stalled connection delays nobody.

A client hop takes ClientCredentials in place of insecure credentials:

hop := mtls.ClientConfig{Name: "api-to-store", Files: files, Mode: hopMode,
	ServerName: "store.platform.svc.cluster.local", ExpectedServerIDs: expected}
conn, err := grpc.NewClient(target, grpc.WithTransportCredentials(mtls.NewClientCredentials(hop)))

Modes

A listener runs ModeOff, ModePermissive or ModeRequired; a client hop runs ClientOff or ClientOn. Off is today's behaviour: plaintext, no checks. Permissive accepts TLS and plaintext, runs every check and counts what it would refuse. Required accepts TLS from an allow-listed name and lets plaintext reach only the health paths and the gRPC health service. The mode is read on every handshake, request and RPC through a ModeSource: StaticMode for a value from the environment (ModeFromEnv), or a FlagModeSource over a FlagReader for a feature flag with the environment value as fallback. A flag that is missing or malformed keeps the last accepted value, and a flip to required is refused while the allow-list is empty. A required mode that any source yields while the list is empty is served as permissive and logged once, so a static mode from the environment and a flag fallback of required behave the same.

Identity

Every peer is verified in tls.Config.VerifyConnection, which Go runs on resumed sessions too: the chain against the roots loaded at that moment, then exactly one URI SAN with the spiffe scheme, then the AllowList. The allow-list is re-checked on every request and RPC, so a removed name is refused at its next call; the connection itself ends at the server's maximum connection age. The chain verdict is kept with the connection: after a flip to required, a TLS connection admitted under permissive with a chain that did not verify is treated as plaintext, health paths only, until the service closes it. Handlers read the caller through PeerFromContext; Peer.ID is the name the certificate carried and is authenticated only when Peer.ChainVerified is set, so under off and permissive a handler must not authorize on the ID alone.

Files

Files reads the certificate, key and trust bundle named by FileConfig (E2B_TLS_CERT_FILE, E2B_TLS_KEY_FILE and E2B_TLS_CA_FILE through FileConfigFromEnv) and re-reads them every minute. A new set replaces the old only when the key matches the certificate and every PEM block parses; otherwise the previous set keeps serving and the failure is counted. The process starts whatever the files hold; expiry is a metric, never fatal.

Metrics

Metrics records, on the meter named after this package and with the e2b_mtls_ prefix, handshakes by outcome, refusals and would-be refusals by reason, plaintext requests and open plaintext connections, mTLS connections by caller, the mode in force per listener and client hop with its source, the certificate's and chain's expiry, reloads by outcome and the loaded roots by fingerprint. Pass Metrics explicitly in tests; DefaultMetrics builds them on the global provider otherwise. The caller attribute is bounded by the allow-list, since only an admitted name is counted; a wildcard entry makes it one series per ServiceAccount it matches. The chain expiry is the earliest not-after among the leaf and the intermediates in the certificate file, which is how the intermediate's expiry is reported; no fingerprint is emitted for the intermediate, only for the roots.

A port shared through a multiplexer

When a Listener sits in front of a multiplexer that wraps connections in its own type, the servers behind it cannot see the *tls.Conn. The listener remembers what it established per remote address; hand (*Listener).ConnState to the gRPC credentials through WithConnStateLookup and to the guard through WithGuardConnStateLookup. A port that carries gRPC offers h2 as well, since grpc-go clients require it:

l := mtls.NewListener(inner, cfg, mtls.WithNextProtos("h2", "http/1.1"))

Closing connections the policy no longer admits

Neither attach point ends a connection on its own when the policy changes: a plaintext connection opened under permissive keeps serving health paths after a flip to required, and so does a TLS connection whose chain did not verify; a name removed from the allow-list is refused at every request or RPC but keeps its connection. Listener and ServerCredentials record the connections they admitted, in every mode. CloseUnverified closes every connection a required handshake would refuse now, plaintext a weaker mode admitted, unverified TLS and a name the allow-list does not admit alike, which a service calls while its mode is required; for a configuration from Process.Listener over a flag the process's watcher does it, so the service adds no flip handler of its own. CloseByPeer closes every TLS connection of one name, which is how a removed name's keep-alive HTTP connection ends, since http.Server has no connection age. gRPC connections also end at the server's maximum connection age.

Index

Constants

View Source
const (
	CertFileEnv = "E2B_TLS_CERT_FILE"
	KeyFileEnv  = "E2B_TLS_KEY_FILE"
	CAFileEnv   = "E2B_TLS_CA_FILE"

	DefaultCertFile = "/var/run/e2b/tls/tls.crt"
	DefaultKeyFile  = "/var/run/e2b/tls/tls.key"
	DefaultCAFile   = "/var/run/e2b/trust/ca.crt"

	// DefaultReloadInterval is how often the files are re-read. A renewal
	// written by the certificate manager reaches new handshakes within it.
	DefaultReloadInterval = time.Minute
)

Environment variables naming the files, and the paths the chart mounts them at.

View Source
const (
	MetricHandshakes        = "e2b_mtls_handshakes_total"
	MetricRefused           = "e2b_mtls_refused_total"
	MetricWouldReject       = "e2b_mtls_would_reject_total"
	MetricPlaintextRequests = "e2b_mtls_plaintext_requests_total"
	MetricPlaintextOpen     = "e2b_mtls_plaintext_connections"
	MetricConnections       = "e2b_mtls_connections_total"
	MetricMode              = "e2b_mtls_mode"
	MetricClientMode        = "e2b_mtls_client_mode"
	MetricNotAfter          = "e2b_mtls_certificate_not_after_seconds"
	MetricReloads           = "e2b_mtls_reloads_total"
	MetricRootsLoaded       = "e2b_mtls_roots_loaded"
)

Instrument names. The prefix is what the collectors' include lists carry.

View Source
const (
	AttrListener    = "listener"
	AttrClientHop   = "client_hop"
	AttrOutcome     = "outcome"
	AttrReason      = "reason"
	AttrKind        = "kind"
	AttrCaller      = "caller"
	AttrMode        = "mode"
	AttrSource      = "source"
	AttrFingerprint = "fingerprint"
)

Attribute keys.

View Source
const (
	// OutcomeTLS: a TLS handshake completed and the peer was admitted.
	OutcomeTLS = "tls"
	// OutcomePlaintext: the connection was admitted as plaintext.
	OutcomePlaintext = "plaintext"
	// OutcomeRefused: the policy refused a TLS peer at the handshake.
	OutcomeRefused = "refused"
	// OutcomeFailed: the TLS handshake itself failed.
	OutcomeFailed = "failed"
	// OutcomeClosed: the peer closed the connection before its first byte,
	// as a TCP health check or a port probe does.
	OutcomeClosed = "closed"
	// OutcomeTimeout: the first byte or the handshake did not arrive in time.
	OutcomeTimeout = "timeout"

	KindHandshake = "handshake"
	KindGRPC      = "grpc"
	KindHTTP      = "http"
	KindLeaf      = "leaf"
	KindChain     = "chain"

	ReloadLoaded    = "loaded"
	ReloadUnchanged = "unchanged"
	ReloadFailed    = "failed"
)

Attribute values.

View Source
const (
	// SourceFallback means the mode in force is the environment value.
	SourceFallback = "fallback"
	// SourceFlag means a flag value has been accepted.
	SourceFlag = "flag"
	// SourceRefused means the value the flag serves is refused, so the mode
	// in force is the one from before it.
	SourceRefused = "refused"
)

Values of the source attribute on the mode gauges.

View Source
const (
	// DefaultHandshakeTimeout bounds the first-byte read and the TLS handshake
	// together, so a silent or stalled connection holds nothing for long.
	DefaultHandshakeTimeout = 5 * time.Second
)
View Source
const DefaultWatchInterval = 10 * time.Second

DefaultWatchInterval is how often a mode that comes from a flag is re-read when no traffic reads it.

Variables

View Source
var (
	// ErrNoCertificateLoaded is returned to a handshake while no consistent
	// set of files has loaded yet.
	ErrNoCertificateLoaded = errors.New("mtls: no certificate loaded")
	// ErrNoRootsLoaded is returned when a peer must be verified and no trust
	// bundle has loaded yet.
	ErrNoRootsLoaded = errors.New("mtls: no trust bundle loaded")
	// ErrInvalidBundle reports a certificate file or trust bundle in which some
	// PEM block is not a certificate that parses.
	ErrInvalidBundle = errors.New("mtls: bundle must be one or more PEM certificates")
	// ErrInvalidAllowList reports an allow-list entry that is not a SPIFFE ID,
	// or a wildcard where none is allowed.
	ErrInvalidAllowList = errors.New("mtls: invalid allow-list entry")
	// ErrInvalidMode reports a mode value that is not off, permissive or
	// required (or on/off for a client hop).
	ErrInvalidMode = errors.New("mtls: invalid mode")
)
View Source
var ErrNoCertificateConfigured = errors.New("mtls: a mode other than off needs certificate files, and " + CertFileEnv + " is unset")

ErrNoCertificateConfigured refuses a mode other than off in a process whose certificate files are not configured.

Functions

func ContextWithPeer

func ContextWithPeer(ctx context.Context, p Peer) context.Context

ContextWithPeer returns ctx carrying p.

func EnvPrefix

func EnvPrefix(key string) string

EnvPrefix is the prefix of the variables a chart renders for a listener or client hop key: E2B_TLS_, the key upper-cased with '-' as '_', then '_'.

func NewHTTPTransport

func NewHTTPTransport(cfg ClientConfig, base *http.Transport) *http.Transport

NewHTTPTransport returns a copy of base, or of http.DefaultTransport when base is nil, whose connections follow the hop's mode, read on every dial: off dials plaintext as before; on completes TLS 1.3 with the client certificate and ALPN http/1.1 within base's TLSHandshakeTimeout and verifies the server as ClientCredentials does. Request URLs keep the http scheme: the server's Listener tells TLS from plaintext by the first byte. The hop's mode is reported at once, as NewClientCredentials does. base's proxy is dropped: the hop dials its target directly. When a flag flips the hop, pooled connections dialled in the other mode are dropped; the hop's watcher keeps every transport built on it, so build one per hop.

func PeerID

func PeerID(cert *x509.Certificate) (string, error)

PeerID returns the SPIFFE ID of a leaf certificate as go-spiffe reads it: exactly one URI SAN holding a well-formed SPIFFE ID. A trust domain with uppercase letters is not well formed and is refused here, where an allow-list entry typed that way is lowercased on parse.

func StreamServerInterceptor

func StreamServerInterceptor(cfg ServerConfig) grpc.StreamServerInterceptor

StreamServerInterceptor is UnaryServerInterceptor for streams. Install it through the shared constructor's WithStreamInterceptors.

func UnaryServerInterceptor

func UnaryServerInterceptor(cfg ServerConfig) grpc.UnaryServerInterceptor

UnaryServerInterceptor re-checks the allow-list on every RPC and, on a required listener, lets a plaintext RPC through only to grpc.health.v1. Install it through the shared constructor's WithUnaryInterceptors so it runs after recovery, logging and the deadline.

Types

type AllowList

type AllowList struct {
	// contains filtered or unexported fields
}

AllowList is the set of SPIFFE IDs a listener admits, or the names a client accepts from a server. Entries are full IDs; the only wildcard is a trailing * in the ServiceAccount segment:

spiffe://cluster-a.example.internal/ns/platform/sa/worker-*

A nil *AllowList admits nobody. Replace swaps in a new list atomically and keeps the current one when the new one does not parse.

func ParseAllowList

func ParseAllowList(entries []string, opts ...AllowListOption) (*AllowList, error)

ParseAllowList validates every entry. Blank entries are skipped. An empty result is a valid list that admits nobody: a listener asked to run required with one serves permissive and logs it, and FlagModeSource refuses the flip at the flag.

func (*AllowList) Allows

func (a *AllowList) Allows(id string) bool

Allows reports whether id, in the canonical form PeerID returns, is on the list.

func (*AllowList) Entries

func (a *AllowList) Entries() []string

Entries returns the canonical entries, wildcards with their trailing *.

func (*AllowList) Len

func (a *AllowList) Len() int

Len is the number of entries.

func (*AllowList) Replace

func (a *AllowList) Replace(entries []string) error

Replace parses entries under the options the list was made with and swaps them in. On error the current list stays.

type AllowListOption

type AllowListOption func(*allowListOptions)

AllowListOption configures parsing.

func WithoutWildcards

func WithoutWildcards() AllowListOption

WithoutWildcards refuses entries with a trailing *, for ports whose callers must be named one by one.

type Bundle

type Bundle struct {
	// Certificate has Leaf populated; Certificate.Certificate[1:] are the
	// intermediates the certificate file carried.
	Certificate *tls.Certificate
	// SVID is the same material in go-spiffe's shape, for its TLS callbacks.
	// Its ID is zero when the leaf carries no SPIFFE ID.
	SVID *x509svid.SVID
	// Roots verifies peers; RootCerts are the same certificates for reporting,
	// and Authorities the same again in go-spiffe's shape, served for every
	// trust domain since one certificate authority signs for all of them.
	Roots       *x509.CertPool
	RootCerts   []*x509.Certificate
	Authorities *x509bundle.Bundle
	LoadedAt    time.Time
}

Bundle is one consistent set of loaded material.

type ClientConfig

type ClientConfig struct {
	// Name labels the hop in metrics and logs, for example "api-to-store".
	Name string
	// Files serves the certificate presented and the roots the server is verified against.
	Files *Files
	// Mode is read on every handshake. nil means ClientOff.
	Mode ClientModeSource
	// ServerName is sent as SNI and checked against the server's DNS SANs
	// when set. Leave it empty for a server dialled by IP; the URI SAN check
	// still runs.
	ServerName string
	// ExpectedServerIDs are the server's acceptable SPIFFE IDs; a listener
	// shared by several workloads has several.
	ExpectedServerIDs *AllowList
	// Logger defaults to logger.L().
	Logger logger.Logger
	// Metrics defaults to DefaultMetrics().
	Metrics *Metrics
	// contains filtered or unexported fields
}

ClientConfig is what one client hop needs.

type ClientCredentials

type ClientCredentials struct {
	// contains filtered or unexported fields
}

ClientCredentials implements credentials.TransportCredentials for one client hop. ClientHandshake reads the hop's mode on every handshake: on, it dials TLS with the client certificate and ALPN h2 and verifies the server; off, it returns the connection as plaintext.

func NewClientCredentials

func NewClientCredentials(cfg ClientConfig) *ClientCredentials

NewClientCredentials builds the credentials for one hop and reports the hop's mode at once, so a hop that has not dialled yet is on the gauge.

func (*ClientCredentials) ClientHandshake

func (c *ClientCredentials) ClientHandshake(ctx context.Context, _ string, raw net.Conn) (net.Conn, credentials.AuthInfo, error)

ClientHandshake implements credentials.TransportCredentials. The authority gRPC passes is not used for verification; ServerName and ExpectedServerIDs are, because several hops dial their server by IP.

func (*ClientCredentials) Clone

Clone implements credentials.TransportCredentials.

func (*ClientCredentials) Info

Info implements credentials.TransportCredentials.

func (*ClientCredentials) OverrideServerName

func (c *ClientCredentials) OverrideServerName(string) error

OverrideServerName implements credentials.TransportCredentials; the server name comes from the configuration.

func (*ClientCredentials) ServerHandshake

func (c *ClientCredentials) ServerHandshake(net.Conn) (net.Conn, credentials.AuthInfo, error)

ServerHandshake implements credentials.TransportCredentials; a client's credentials never accept.

type ClientMode

type ClientMode int

ClientMode is whether a client hop dials TLS.

const (
	// ClientOff dials plaintext.
	ClientOff ClientMode = iota
	// ClientOn dials TLS with the client certificate and verifies the server.
	ClientOn
)

func ClientModeFromEnv

func ClientModeFromEnv(name string) (ClientMode, error)

ClientModeFromEnv parses the client hop mode named by the environment variable; unset or blank is ClientOff.

func ParseClientMode

func ParseClientMode(value string) (ClientMode, error)

ParseClientMode reads on or off, ignoring case and surrounding space.

func (ClientMode) String

func (m ClientMode) String() string

type ClientModeSource

type ClientModeSource interface {
	ClientMode(ctx context.Context) ClientMode
}

ClientModeSource yields whether a client hop dials TLS; read on every handshake, because clients keep connections for a long time.

type ConnState

type ConnState struct {
	// TLS is false for a connection admitted as plaintext.
	TLS bool
	// ChainVerified reports whether the peer's chain reached a loaded root
	// at the handshake. It is false for a TLS connection admitted under
	// permissive with a chain that did not verify; required treats such a
	// connection as plaintext until the service closes it.
	ChainVerified bool
	// State is the completed handshake when TLS is true.
	State tls.ConnectionState
}

ConnState is what the listener established for one accepted connection. A server that receives the connection through a multiplexer hiding its concrete type asks for it by remote address.

type ConnStateLookup

type ConnStateLookup func(remoteAddr string) (ConnState, bool)

ConnStateLookup answers whether the connection from remoteAddr completed TLS, or was admitted as plaintext, before it reached the server asking. (*Listener).ConnState is one.

type CredentialsOption

type CredentialsOption func(*ServerCredentials)

CredentialsOption configures NewServerCredentials.

func WithConnStateLookup

func WithConnStateLookup(lookup ConnStateLookup) CredentialsOption

WithConnStateLookup consults lookup before peeking, for a server that receives connections a Listener already classified, through a multiplexer that hides their type.

type FileConfig

type FileConfig struct {
	CertFile string
	KeyFile  string
	CAFile   string
}

FileConfig names the certificate, its key and the trust bundle.

func FileConfigFromEnv

func FileConfigFromEnv() FileConfig

FileConfigFromEnv reads the three paths from the environment, defaulting each.

type Files

type Files struct {
	// contains filtered or unexported fields
}

Files reads the certificate, key and trust bundle from disk, re-reads them on a timer and on demand, and serves the last good set. A read that fails or is inconsistent keeps the previous set; the process starts whatever the files hold.

func NewFiles

func NewFiles(ctx context.Context, cfg FileConfig, opts ...FilesOption) *Files

NewFiles loads the files once and returns. It never fails: with missing or inconsistent files Bundle is nil until a later reload succeeds, and the failure is logged.

func (*Files) Bundle

func (f *Files) Bundle() *Bundle

Bundle returns the current set, or nil when nothing has loaded yet.

func (*Files) GetX509BundleForTrustDomain

func (f *Files) GetX509BundleForTrustDomain(spiffeid.TrustDomain) (*x509bundle.Bundle, error)

GetX509BundleForTrustDomain implements x509bundle.Source over the loaded files. One certificate authority signs for every trust domain, so the same roots answer whatever trust domain a peer's ID names; the allow-list is what tells the trust domains apart.

func (*Files) GetX509SVID

func (f *Files) GetX509SVID() (*x509svid.SVID, error)

GetX509SVID implements x509svid.Source over the loaded files, so go-spiffe's TLS callbacks present the certificate loaded now.

func (*Files) Reload

func (f *Files) Reload(ctx context.Context) error

Reload reads all three files now. The new set replaces the old only when the key matches the certificate and every PEM block of the certificate file and the trust bundle is a certificate that parses.

func (*Files) Start

func (f *Files) Start(ctx context.Context)

Start re-reads the files every interval until ctx ends.

type FilesOption

type FilesOption func(*Files)

FilesOption configures NewFiles.

func WithFilesLogger

func WithFilesLogger(log logger.Logger) FilesOption

WithFilesLogger replaces logger.L().

func WithFilesMetrics

func WithFilesMetrics(m *Metrics) FilesOption

WithFilesMetrics replaces DefaultMetrics().

func WithReloadInterval

func WithReloadInterval(interval time.Duration) FilesOption

WithReloadInterval replaces DefaultReloadInterval.

type FlagClientModeSource

type FlagClientModeSource struct {
	// contains filtered or unexported fields
}

FlagClientModeSource reads a client hop's mode from a flag, starting from the environment fallback, and keeps the last accepted value when the flag is missing or malformed.

func NewFlagClientModeSource

func NewFlagClientModeSource(reader FlagReader, key string, fallback ClientMode, opts ...ModeOption) *FlagClientModeSource

NewFlagClientModeSource starts at fallback with SourceFallback.

func (*FlagClientModeSource) ClientMode

func (s *FlagClientModeSource) ClientMode(ctx context.Context) ClientMode

ClientMode implements ClientModeSource.

func (*FlagClientModeSource) ClientModeWithSource

func (s *FlagClientModeSource) ClientModeWithSource(ctx context.Context) (ClientMode, string)

ClientModeWithSource returns the mode in force and its source, read together.

func (FlagClientModeSource) Source

func (s FlagClientModeSource) Source() string

Source reports where the mode in force came from, or SourceRefused while the flag's value is refused.

type FlagModeSource

type FlagModeSource struct {
	// contains filtered or unexported fields
}

FlagModeSource reads a listener's mode from a flag, starting from the environment fallback. It keeps the last accepted value when the flag is missing or malformed, and refuses a flip to required while the allow-list is empty.

func NewFlagModeSource

func NewFlagModeSource(reader FlagReader, key string, fallback Mode, allow *AllowList, opts ...ModeOption) *FlagModeSource

NewFlagModeSource starts at fallback with SourceFallback.

func (*FlagModeSource) Mode

func (s *FlagModeSource) Mode(ctx context.Context) Mode

Mode implements ModeSource.

func (*FlagModeSource) ModeWithSource

func (s *FlagModeSource) ModeWithSource(ctx context.Context) (Mode, string)

ModeWithSource returns the mode in force and its source, read together.

func (FlagModeSource) Source

func (s FlagModeSource) Source() string

Source reports where the mode in force came from, or SourceRefused while the flag's value is refused.

type FlagReader

type FlagReader interface {
	String(ctx context.Context, key, fallback string) string
}

FlagReader is the one method the package needs from a feature-flag client. It returns fallback when the flag is missing, so an adapter over any client is a few lines and the package imports none.

type GuardOption

type GuardOption func(*HTTPGuard)

GuardOption configures NewHTTPGuard.

func WithGuardConnStateLookup

func WithGuardConnStateLookup(lookup ConnStateLookup) GuardOption

WithGuardConnStateLookup hands the guard the listener's ConnState, which carries each connection's chain verdict; r.TLS does not, because the package verifies in VerifyConnection. A required listener needs it: without it every TLS request on a connection the package terminated is treated as unverified, plaintext in effect. It is also how a server behind a multiplexer that hides the connection type learns what the listener saw.

type HTTPGuard

type HTTPGuard struct {
	// contains filtered or unexported fields
}

HTTPGuard applies the listener's policy to every request. On a required listener a plaintext request reaches only a configured health path, by GET or HEAD; everything else plaintext is answered 403. A TLS request's name is re-checked against the allow-list on every request, so a removed name is refused at its next call. net/http hands every HTTP/2 stream to the handler as its own request, so each stream on a plaintext h2c connection is checked.

func NewHTTPGuard

func NewHTTPGuard(cfg ServerConfig, healthPaths []string, next http.Handler, opts ...GuardOption) *HTTPGuard

NewHTTPGuard wraps next. healthPaths are exact paths, such as "/health" and "/ready"; the query string is not part of the path. Each is trimmed and blanks are skipped, as a list read from the environment needs.

func (*HTTPGuard) ServeHTTP

func (g *HTTPGuard) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

type HopSettings

type HopSettings struct {
	// Mode is off or on; blank is off.
	Mode string `env:"CLIENT_MODE"`
	// Expect are the server's acceptable SPIFFE IDs.
	Expect []string `env:"EXPECT"`
	// ServerName is the DNS name checked against the server's certificate,
	// empty for a server dialled by IP.
	ServerName string `env:"SERVER_NAME"`
}

HopSettings are one client hop's settings as a chart renders them under EnvPrefix(key); see ListenerSettings. Process.Hop parses them.

func HopSettingsFromEnv

func HopSettingsFromEnv(key string) HopSettings

HopSettingsFromEnv reads the variables the chart renders for the client hop key. An unset variable reads as empty.

type Listener

type Listener struct {
	// contains filtered or unexported fields
}

Listener classifies each connection by its first byte, completes TLS itself and hands the server either the *tls.Conn, unwrapped so net/http populates r.TLS, or a *PlaintextConn. Classification and the handshake run in their own goroutine under the handshake deadline, so a silent, one-byte or stalled connection delays no other caller. In ModeOff connections pass through unread, recorded as plaintext so that a later CloseUnverified reaches them.

The TLS branch offers http/1.1 unless WithNextProtos says otherwise. Put the listener in front of http.Server.Serve; for a port shared through a multiplexer, put it in front of the multiplexer, offer the protocols the servers behind it speak, and hand them ConnState.

func NewListener

func NewListener(inner net.Listener, cfg ServerConfig, opts ...ListenerOption) *Listener

NewListener wraps inner and starts accepting. The policy is evaluated once here, so a required mode with an empty allow-list is reported at startup rather than at the first connection.

func WrapHTTPServer

func WrapHTTPServer(s *http.Server, inner net.Listener, cfg ServerConfig, healthPaths []string, opts ...ListenerOption) *Listener

WrapHTTPServer puts s behind a Listener on inner: s.Handler is wrapped in the guard, built on cfg with healthPaths and the listener's connection lookup. Serve the returned Listener.

func (*Listener) Accept

func (l *Listener) Accept() (net.Conn, error)

Accept implements net.Listener.

func (*Listener) Addr

func (l *Listener) Addr() net.Addr

Addr implements net.Listener.

func (*Listener) Close

func (l *Listener) Close() error

Close implements net.Listener. A connection still being classified is closed. Closing twice is fine: http.Server.Close closes the listener it was given as well.

func (*Listener) CloseByPeer

func (l *Listener) CloseByPeer(id string) int

CloseByPeer closes every open TLS connection whose peer is id and returns how many it closed: how a name removed from the allow-list loses its keep-alive connections, since http.Server has no connection age.

func (*Listener) CloseUnverified

func (l *Listener) CloseUnverified() (int, error)

CloseUnverified closes every open connection required would not admit now, the plaintext ones a weaker mode admitted, the TLS ones whose chain did not verify and the TLS ones whose name is not on the allow-list, and returns how many: what a service calls when its mode flips to required, so callers reconnect and meet the new policy instead of riding a connection opened under the old one. A plaintext connection required itself admitted, for a health check, stays open.

func (*Listener) ConnState

func (l *Listener) ConnState(remoteAddr string) (ConnState, bool)

ConnState reports what the listener established for the open connection from remoteAddr. It is a ConnStateLookup. Remote addresses must be unique among open connections, as on TCP: two connections sharing one are both reported unverified.

type ListenerOption

type ListenerOption func(*Listener)

ListenerOption configures NewListener.

func WithNextProtos

func WithNextProtos(protos ...string) ListenerOption

WithNextProtos replaces the ALPN protocols the TLS branch offers, http/1.1 alone by default. A port that also carries gRPC behind a multiplexer offers "h2" as well, since grpc-go clients require it.

type ListenerSettings

type ListenerSettings struct {
	// Mode is off, permissive or required; blank is off.
	Mode string `env:"MODE"`
	// Allow is the allow-list, one SPIFFE ID per entry.
	Allow []string `env:"ALLOW"`
	// HealthPaths are the exact paths a plaintext request may reach under required.
	HealthPaths []string `env:"HEALTH_PATHS"`
}

ListenerSettings are one listener's settings as a chart renders them under EnvPrefix(key). A configuration read with github.com/caarlos0/env holds a field of this type under that prefix; ListenerSettingsFromEnv reads the same variables directly. Process.Listener parses them.

func ListenerSettingsFromEnv

func ListenerSettingsFromEnv(key string) ListenerSettings

ListenerSettingsFromEnv reads the variables the chart renders for the listener key. An unset variable reads as empty.

type Metrics

type Metrics struct {
	// contains filtered or unexported fields
}

Metrics holds the package instruments. A nil *Metrics records nothing.

func DefaultMetrics

func DefaultMetrics() *Metrics

DefaultMetrics builds the instruments on the global meter provider once. On failure it logs and returns nil, which records nothing.

func NewMetrics

func NewMetrics(provider metric.MeterProvider) (*Metrics, error)

NewMetrics creates the instruments on provider's meter named after this package.

type Mode

type Mode int

Mode is what a listener accepts.

const (
	// ModeOff accepts plaintext only and checks nothing: today's behaviour.
	ModeOff Mode = iota
	// ModePermissive accepts TLS and plaintext, runs every check, counts what
	// it would refuse, and enforces nothing.
	ModePermissive
	// ModeRequired accepts TLS from an allow-listed name; plaintext reaches
	// only the health paths and the gRPC health service.
	ModeRequired
)

func ModeFromEnv

func ModeFromEnv(name string) (Mode, error)

ModeFromEnv parses the listener mode named by the environment variable. An unset or blank variable is ModeOff; any other value that is not a mode is an error, so a typo cannot silently read as off.

func ParseMode

func ParseMode(value string) (Mode, error)

ParseMode reads off, permissive or required, ignoring case and surrounding space.

func (Mode) String

func (m Mode) String() string

type ModeOption

type ModeOption func(*modeOptions)

ModeOption configures a flag-backed source.

func WithModeLogger

func WithModeLogger(log logger.Logger) ModeOption

WithModeLogger replaces logger.L().

type ModeSource

type ModeSource interface {
	Mode(ctx context.Context) Mode
}

ModeSource yields the mode a listener applies. It is read on every handshake, request and RPC, so a flip needs no restart.

type Peer

type Peer struct {
	// ID is the SPIFFE ID the caller's certificate carried, when it has one
	// valid SPIFFE SAN; empty otherwise. It is authenticated only when
	// ChainVerified is set: under off and permissive the package admits a
	// certificate whose chain did not verify, and reports its name as
	// presented, so a handler must not authorize on ID alone.
	ID string
	// TLS is false for a connection admitted without TLS.
	TLS bool
	// ChainVerified reports whether the certificate's chain reached a loaded
	// root at the handshake. True for every caller admitted to a business
	// path under required; false for a plaintext or unverified probe that
	// required admits to a health path, and for a self-signed or wrong-root
	// certificate admitted under permissive or off.
	ChainVerified bool
}

Peer is the caller as the package established it, available to handlers through PeerFromContext.

func PeerFromContext

func PeerFromContext(ctx context.Context) (Peer, bool)

PeerFromContext returns the caller the interceptors or the HTTP guard established.

type PlaintextAuthInfo

type PlaintextAuthInfo struct {
	credentials.CommonAuthInfo
}

PlaintextAuthInfo is the peer.AuthInfo of a connection admitted without TLS, so interceptors can tell it from a TLS connection.

func (PlaintextAuthInfo) AuthType

func (PlaintextAuthInfo) AuthType() string

AuthType implements credentials.AuthInfo.

type PlaintextConn

type PlaintextConn struct {
	// contains filtered or unexported fields
}

PlaintextConn marks a connection the listener admitted without TLS. It does not implement ConnectionState, so net/http leaves r.TLS nil.

func (*PlaintextConn) Close

func (c *PlaintextConn) Close() error

func (*PlaintextConn) CloseWrite

func (c *PlaintextConn) CloseWrite() error

CloseWrite half-closes the connection under the hook; a *PlaintextConn therefore keeps the half-close of the TCP connection it wraps.

func (*PlaintextConn) ReadFrom

func (c *PlaintextConn) ReadFrom(r io.Reader) (int64, error)

ReadFrom keeps the sendfile path of the connection under the hook.

type Process

type Process struct {
	// contains filtered or unexported fields
}

Process is one process's mutual TLS: its certificate files, its instruments, its flag reader, and whether certificate files are configured at all. Build it once, after the logger and the meter provider, and derive every listener and client hop from it.

The chart sets E2B_TLS_CERT_FILE only where it mounts a certificate. Where it is unset the process loads nothing, reads no flag and records nothing, and every listener and hop it builds is off: the wire and the process behave as before this package.

A mode that comes from a flag is also re-read every watch interval, so its gauge follows the flag without traffic, and while a listener is required, each re-read closes, on every Listener and ServerCredentials built on its configuration, the connections required would refuse.

func NewProcess

func NewProcess(ctx context.Context, provider metric.MeterProvider, reader FlagReader, log logger.Logger, opts ...ProcessOption) (*Process, error)

NewProcess loads the certificate files and re-reads them every minute until ctx ends, and creates the instruments on provider. reader is the service's flag client, or nil for a service whose modes come from the environment alone; a nil log means logger.L().

func (*Process) Enabled

func (p *Process) Enabled() bool

Enabled reports whether certificate files are configured.

func (*Process) Hop

func (p *Process) Hop(key, flagKey string, settings HopSettings) (ClientConfig, error)

Hop builds the configuration of the client hop a chart renders under key, named key in metrics and logs; its mode comes from flagKey as for Listener. The expected server names refuse a wildcard, as the chart does. A hop on from the environment needs at least one; a flag-backed hop without one builds, and its flag cannot turn it on.

func (*Process) Listener

func (p *Process) Listener(key, flagKey string, settings ListenerSettings, opts ...AllowListOption) (ServerConfig, error)

Listener builds the configuration of the listener a chart renders under key, named key in metrics and logs. Its mode comes from the flag flagKey, with settings.Mode as the fallback, when the process has a flag reader and flagKey is set, and from settings.Mode alone otherwise; blank is off. A malformed mode or allow-list is an error naming its variable; opts apply to the allow-list.

type ProcessOption

type ProcessOption func(*processOptions)

ProcessOption configures NewProcess.

func WithFileConfig

func WithFileConfig(cfg FileConfig) ProcessOption

WithFileConfig reads the certificate files from cfg instead of the environment, and counts them as configured whether or not they exist yet.

func WithWatchInterval

func WithWatchInterval(interval time.Duration) ProcessOption

WithWatchInterval replaces DefaultWatchInterval.

type Reason

type Reason string

Reason names why a peer was refused, or would have been refused in permissive mode. The values are metric attribute values.

const (
	// ReasonNoCertificate: the peer presented no certificate.
	ReasonNoCertificate Reason = "no_certificate"
	// ReasonUnknownAuthority: the chain does not reach a loaded root.
	ReasonUnknownAuthority Reason = "unknown_authority"
	// ReasonExpired: a certificate in the chain is outside its validity.
	ReasonExpired Reason = "expired"
	// ReasonKeyUsage: the leaf lacks the client (or server) authentication usage.
	ReasonKeyUsage Reason = "key_usage"
	// ReasonChain: any other chain verification failure.
	ReasonChain Reason = "chain"
	// ReasonSAN: not exactly one URI SAN with the spiffe scheme.
	ReasonSAN Reason = "san"
	// ReasonNotAllowed: the name is well formed but not on the list.
	ReasonNotAllowed Reason = "not_allowed"
	// ReasonHostname: the server's DNS SANs do not include the configured name.
	ReasonHostname Reason = "hostname"
	// ReasonNoALPN: the peer did not negotiate h2 on a gRPC connection.
	ReasonNoALPN Reason = "no_alpn"
	// ReasonPlaintext: a plaintext request or RPC on a required listener.
	ReasonPlaintext Reason = "plaintext"
	// ReasonUnverifiedChain: a request or RPC on a required listener over a
	// TLS connection whose chain did not verify at its handshake, admitted
	// under permissive.
	ReasonUnverifiedChain Reason = "unverified_chain"
)

type RejectionError

type RejectionError struct {
	Reason Reason
	Err    error
}

RejectionError is returned from a handshake, request or RPC check when the peer is refused.

func (*RejectionError) Error

func (e *RejectionError) Error() string

func (*RejectionError) Unwrap

func (e *RejectionError) Unwrap() error

type ServerConfig

type ServerConfig struct {
	// Name labels the listener in metrics and logs, for example "grpc-internal".
	Name string
	// Files serves the certificate presented and the roots peers are verified against.
	Files *Files
	// Mode is read on every handshake, request and RPC. nil means ModeOff.
	Mode ModeSource
	// Allow is the set of SPIFFE IDs admitted. nil or empty admits nobody.
	Allow *AllowList
	// HandshakeTimeout bounds classification plus handshake; zero means DefaultHandshakeTimeout.
	HandshakeTimeout time.Duration
	// Logger defaults to logger.L().
	Logger logger.Logger
	// Metrics defaults to DefaultMetrics().
	Metrics *Metrics
	// contains filtered or unexported fields
}

ServerConfig is what one listener needs: its material, its policy and its name.

type ServerCredentials

type ServerCredentials struct {
	// contains filtered or unexported fields
}

ServerCredentials implements credentials.TransportCredentials for a gRPC server. ServerHandshake peeks the first byte under the handshake deadline: a TLS record gets a TLS handshake with ALPN h2 and returns TLSAuthInfo, which embeds credentials.TLSInfo; anything else is returned as plaintext with PlaintextAuthInfo. In ModeOff the connection passes through unread, recorded as plaintext so that a later CloseUnverified reaches it.

func NewServerCredentials

func NewServerCredentials(cfg ServerConfig, opts ...CredentialsOption) *ServerCredentials

NewServerCredentials builds the credentials for one listener. The policy is evaluated once here, so a required mode with an empty allow-list is reported at startup rather than at the first connection.

func (*ServerCredentials) ClientHandshake

ClientHandshake implements credentials.TransportCredentials; a server's credentials never dial.

func (*ServerCredentials) Clone

Clone implements credentials.TransportCredentials.

func (*ServerCredentials) CloseByPeer

func (c *ServerCredentials) CloseByPeer(id string) int

CloseByPeer closes every open TLS connection whose peer is id and returns how many it closed, for a name removed from the allow-list; the server's maximum connection age ends such connections as well.

func (*ServerCredentials) CloseUnverified

func (c *ServerCredentials) CloseUnverified() (int, error)

CloseUnverified closes every open connection required would not admit now, the plaintext ones a weaker mode admitted, the TLS ones whose chain did not verify and the TLS ones whose name is not on the allow-list, and returns how many: what a service calls when its mode flips to required. A plaintext connection required itself admitted, for a health check, stays open. A connection a Listener classified in front of a multiplexer is the listener's to close.

func (*ServerCredentials) Info

Info implements credentials.TransportCredentials.

func (*ServerCredentials) OverrideServerName

func (c *ServerCredentials) OverrideServerName(string) error

OverrideServerName implements credentials.TransportCredentials; gRPC no longer calls it and the server name comes from the configuration.

func (*ServerCredentials) ServerHandshake

func (c *ServerCredentials) ServerHandshake(raw net.Conn) (net.Conn, credentials.AuthInfo, error)

ServerHandshake implements credentials.TransportCredentials.

type StaticClientMode

type StaticClientMode ClientMode

StaticClientMode is a ClientModeSource that never changes.

func (StaticClientMode) ClientMode

ClientMode implements ClientModeSource.

type StaticMode

type StaticMode Mode

StaticMode is a ModeSource that never changes, for a service whose mode comes from the environment alone.

func (StaticMode) Mode

func (m StaticMode) Mode(context.Context) Mode

Mode implements ModeSource.

type TLSAuthInfo

type TLSAuthInfo struct {
	credentials.TLSInfo

	// ChainVerified reports whether the peer's chain reached a loaded root
	// at the handshake. False for a connection admitted under permissive
	// with a chain that did not verify.
	ChainVerified bool
}

TLSAuthInfo is the peer.AuthInfo of a TLS connection: grpc-go's TLSInfo, built the way its own credentials build it so gRPC tooling reads the usual shape, plus the verdict of the handshake checks, which the per-RPC check needs after a flip to required.

Directories

Path Synopsis
Package mtlstest mints throwaway certificate hierarchies for tests of the mtls package and of the services that use it: a root, an intermediate and leaves carrying a SPIFFE URI SAN, all ECDSA P-256, optionally written to a temporary directory laid out the way the chart mounts them.
Package mtlstest mints throwaway certificate hierarchies for tests of the mtls package and of the services that use it: a root, an intermediate and leaves carrying a SPIFFE URI SAN, all ECDSA P-256, optionally written to a temporary directory laid out the way the chart mounts them.
Package servicetest helps a service's tests prove its mtls wiring: a configured Process whose instruments the test reads, a flag client the test drives, credentials that count a dial site's handshakes, and a plaintext gRPC server to dial.
Package servicetest helps a service's tests prove its mtls wiring: a configured Process whose instruments the test reads, a flag client the test drives, credentials that count a dial site's handshakes, and a plaintext gRPC server to dial.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL