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
- Variables
- func ContextWithPeer(ctx context.Context, p Peer) context.Context
- func EnvPrefix(key string) string
- func NewHTTPTransport(cfg ClientConfig, base *http.Transport) *http.Transport
- func PeerID(cert *x509.Certificate) (string, error)
- func StreamServerInterceptor(cfg ServerConfig) grpc.StreamServerInterceptor
- func UnaryServerInterceptor(cfg ServerConfig) grpc.UnaryServerInterceptor
- type AllowList
- type AllowListOption
- type Bundle
- type ClientConfig
- type ClientCredentials
- func (c *ClientCredentials) ClientHandshake(ctx context.Context, _ string, raw net.Conn) (net.Conn, credentials.AuthInfo, error)
- func (c *ClientCredentials) Clone() credentials.TransportCredentials
- func (c *ClientCredentials) Info() credentials.ProtocolInfo
- func (c *ClientCredentials) OverrideServerName(string) error
- func (c *ClientCredentials) ServerHandshake(net.Conn) (net.Conn, credentials.AuthInfo, error)
- type ClientMode
- type ClientModeSource
- type ConnState
- type ConnStateLookup
- type CredentialsOption
- type FileConfig
- type Files
- type FilesOption
- type FlagClientModeSource
- type FlagModeSource
- type FlagReader
- type GuardOption
- type HTTPGuard
- type HopSettings
- type Listener
- type ListenerOption
- type ListenerSettings
- type Metrics
- type Mode
- type ModeOption
- type ModeSource
- type Peer
- type PlaintextAuthInfo
- type PlaintextConn
- type Process
- type ProcessOption
- type Reason
- type RejectionError
- type ServerConfig
- type ServerCredentials
- func (c *ServerCredentials) ClientHandshake(context.Context, string, net.Conn) (net.Conn, credentials.AuthInfo, error)
- func (c *ServerCredentials) Clone() credentials.TransportCredentials
- func (c *ServerCredentials) CloseByPeer(id string) int
- func (c *ServerCredentials) CloseUnverified() (int, error)
- func (c *ServerCredentials) Info() credentials.ProtocolInfo
- func (c *ServerCredentials) OverrideServerName(string) error
- func (c *ServerCredentials) ServerHandshake(raw net.Conn) (net.Conn, credentials.AuthInfo, error)
- type StaticClientMode
- type StaticMode
- type TLSAuthInfo
Constants ¶
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.
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.
const ( AttrListener = "listener" AttrClientHop = "client_hop" AttrOutcome = "outcome" AttrReason = "reason" AttrKind = "kind" AttrCaller = "caller" AttrMode = "mode" AttrSource = "source" AttrFingerprint = "fingerprint" )
Attribute keys.
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.
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.
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 )
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 ¶
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") )
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 ¶
ContextWithPeer returns ctx carrying p.
func EnvPrefix ¶
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 ¶
Allows reports whether id, in the canonical form PeerID returns, is on the list.
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 ¶
func (c *ClientCredentials) Clone() credentials.TransportCredentials
Clone implements credentials.TransportCredentials.
func (*ClientCredentials) Info ¶
func (c *ClientCredentials) Info() credentials.ProtocolInfo
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 ¶
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 ¶
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) 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 ¶
GetX509SVID implements x509svid.Source over the loaded files, so go-spiffe's TLS callbacks present the certificate loaded now.
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.
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.
type FlagReader ¶
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.
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) Close ¶
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 ¶
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 ¶
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.
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 ¶
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.
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 ¶
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.
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) 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.
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) 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 ¶
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 ¶
func (c *ServerCredentials) ClientHandshake(context.Context, string, net.Conn) (net.Conn, credentials.AuthInfo, error)
ClientHandshake implements credentials.TransportCredentials; a server's credentials never dial.
func (*ServerCredentials) Clone ¶
func (c *ServerCredentials) Clone() credentials.TransportCredentials
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 ¶
func (c *ServerCredentials) Info() credentials.ProtocolInfo
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 ¶
func (m StaticClientMode) ClientMode(context.Context) 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.
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.
Source Files
¶
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. |