Documentation
¶
Overview ¶
Package mtls is mutual TLS between services: a Source (the service's live certificate, the trusted roots and who may call it — the Consul driver's follows Consul's CA and intentions) turned into the TLS of a public port and of clients, and the caller of a request: its service, taken from the SPIFFE URI of the certificate it presented.
Certificates are read on every handshake, so a renewed certificate or a rotated root applies to the next connection without restarting anything; connections already open keep the certificates they were made with.
Index ¶
- Variables
- func ClientConfig(src Source, target string, nextProtos ...string) *tls.Config
- func ConnContext(ctx context.Context, conn net.Conn) context.Context
- func GRPCServerOptions(src Source) []grpc.ServerOption
- func HealthMethod(method string) bool
- func Middleware(src Source) func(http.Handler) http.Handler
- func ServerConfig(src Source) *tls.Config
- func WithPeer(ctx context.Context, p Peer) context.Context
- type AuthInfo
- type Failing
- type Peer
- type Platform
- type Source
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoIdentity: the source has no certificate or roots yet. ErrNoIdentity = errors.New("mtls: no certificate or roots yet") // ErrPeer: the peer's certificate is not a service's of this mesh. ErrPeer = errors.New("mtls: peer") )
Errors.
Functions ¶
func ClientConfig ¶
ClientConfig is the TLS of a call to target: the source's certificate, the peer verified against the current roots and as target. nextProtos: h2 for gRPC, http/1.1 for HTTP.
func ConnContext ¶
ConnContext puts an HTTP connection into its requests' context (http.Server.ConnContext), for PeerFrom to read its peer per request. It runs in the server's accept loop, before the TLS handshake when no gRPC matcher read the connection first (a port serving HTTP only): the peer is not known yet, and a handshake here would hold the accept loop.
func GRPCServerOptions ¶
func GRPCServerOptions(src Source) []grpc.ServerOption
GRPCServerOptions are the options of a gRPC server behind an mTLS listener: the peer as auth info, and every call authorized by src, the caller put in its context (PeerFrom).
func HealthMethod ¶ added in v0.6.39
HealthMethod reports whether method is of grpc.health.v1.Health: what a Consul gRPC check calls.
func Middleware ¶
Middleware authorizes every request of an mTLS port: 403 for a caller src refuses, 401 without a service certificate.
func ServerConfig ¶
ServerConfig is the TLS of a port only services of the mesh reach: the source's certificate, a client certificate required and verified against the current roots. It offers h2 (gRPC) and http/1.1.
Types ¶
type AuthInfo ¶
type AuthInfo struct {
credentials.CommonAuthInfo
Peer Peer
}
AuthInfo is the gRPC auth info of a connection the listener's TLS verified.
type Failing ¶
type Failing interface{ Err() error }
Failing is a source that cannot have an identity, and says why.
type Peer ¶
type Peer struct {
// Service is the peer's service name.
Service string
// Namespace, Partition and Datacenter of the service (Consul's; the
// partition is "default" when the URI names none).
Namespace, Partition, Datacenter string
// TrustDomain is the CA's (the URI's host).
TrustDomain string
// URI is its SPIFFE identity:
// spiffe://<trust domain>[/ap/<partition>]/ns/<ns>/dc/<dc>/svc/<service>.
URI string
}
Peer is the service on the other end.
func ParseURI ¶ added in v0.6.21
ParseURI reads a SPIFFE URI in Consul's service identity form: spiffe://<trust domain>[/ap/<partition>]/ns/<ns>/dc/<dc>/svc/<service>, every segment present and non-empty, nothing else.
func PeerFrom ¶
PeerFrom is the peer ctx carries: the one WithPeer set, else the peer of the HTTP connection ConnContext put there, read now — the TLS handshake may complete only after the connection's context is made.
type Platform ¶ added in v0.6.39
type Platform struct {
Src Source
Required bool
// OpenHTTP and OpenGRPC: the paths and methods a plain caller reaches
// when Required.
OpenHTTP func(path string) bool
OpenGRPC func(method string) bool
}
Platform authorizes the calls of the platform port when it serves mutual TLS: a caller with a certificate is authorized by src (its peer put in the context); a plain caller passes when required is false, else only to what open accepts (the probes).
func (Platform) GRPCServerOptions ¶ added in v0.6.39
func (p Platform) GRPCServerOptions() []grpc.ServerOption
GRPCServerOptions are the options of the platform port's gRPC server.
type Source ¶
type Source interface {
// Certificate is the service's current certificate; nil until there is one.
Certificate() *tls.Certificate
// Roots are the CA certificates peers' chains must lead to; nil until known.
Roots() *x509.CertPool
// Authorize decides whether caller (a service name) may call this
// service, and why.
Authorize(caller string) (bool, string)
}
Source is a service's identity.