mtls

package
v1.60.0 Latest Latest
Warning

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

Go to latest
Published: Apr 7, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package mtls facilitates Mutual TLS authentication for SansShell.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func LoadClientCredentials

func LoadClientCredentials(ctx context.Context, loaderName string) (credentials.TransportCredentials, error)

LoadClientCredentials returns transport credentials for SansShell clients, based on the provided `loaderName`

func LoadClientTLS

func LoadClientTLS(clientCertFile, clientKeyFile string, CAPool *x509.CertPool) (credentials.TransportCredentials, error)

LoadClientTLS reads the certificates and keys from disk at the supplied paths, and assembles them into a set of TransportCredentials for the gRPC client.

func LoadRootOfTrust

func LoadRootOfTrust(path string) (*x509.CertPool, error)

LoadRootOfTrust will load an CA root of trust(s) from the given file and return a CertPool to use in validating certificates. All CA's to validate against must be presented together in the PEM file. If the file is a directory, LoadRootOfTrust will load all files in that directory.

func LoadServerCredentials

func LoadServerCredentials(ctx context.Context, loaderName string) (credentials.TransportCredentials, error)

LoadServerCredentials returns transport credentials for a SansShell server as retrieved from the specified `loaderName`. This should be the most commonly used method to generate credentials as this will support reloadable credentials as the TransportCredentials returned are a WrappedTransportCredentials which will check at call time if new certificates are available.

func LoadServerCredentialsWithForceRefresh added in v1.30.0

func LoadServerCredentialsWithForceRefresh(ctx context.Context, loaderName string) (credentials.TransportCredentials, func() error, error)

LoadServerCredentialsWithForceRefresh returns transport credentials along with a function that allows immediately refreshing the credentials

func LoadServerTLS

func LoadServerTLS(clientCertFile, clientKeyFile string, CAPool *x509.CertPool) (credentials.TransportCredentials, error)

LoadServerTLS reads the certificates and keys from disk at the supplied paths, and assembles them into a set of TransportCredentials for the gRPC server. NOTE: This doesn't support reloadable credentials.

func Loaders

func Loaders() []string

Loaders returns the names of all currently registered CredentialLoader implementations as a sorted list of strings.

func NewClientCredentials

func NewClientCredentials(cert tls.Certificate, CAPool *x509.CertPool) credentials.TransportCredentials

NewClientCredentials returns transport credentials for SansShell clients.

func NewServerCredentials

func NewServerCredentials(cert tls.Certificate, CAPool *x509.CertPool) credentials.TransportCredentials

NewServerCredentials creates transport credentials for a SansShell server. NOTE: This doesn't support reloadable credentials.

func Register

func Register(name string, loader CredentialsLoader) error

Register associates a name with a mechanism for loading credentials. Implementations of CredentialsLoader will typically call Register during init()

Types

type ClientCertInfo added in v1.49.0

type ClientCertInfo struct {
	Username   string
	CertIssuer string
	ValidUntil time.Time
	Groups     []string
}

ClientCertInfo contains certificate-based user information

type ClientIdentity added in v1.59.0

type ClientIdentity struct {
	LoaderName string
	Cert       tls.Certificate
}

ClientIdentity represents a single client identity (certificate + loader name) that can be presented during a TLS handshake.

func LoadClientIdentity added in v1.59.0

func LoadClientIdentity(ctx context.Context, loaderName string) (ClientIdentity, error)

LoadClientIdentity loads a client certificate from the named CredentialsLoader and returns it as a ClientIdentity suitable for use with NewMultiIdentityCredentials.

type CredentialsLoader

type CredentialsLoader interface {
	// LoadClientCA returns a CertPool which should be used by a server to
	// validate client certificates.
	// NOTE: The pool returned here will be the only pool used to validate certificates.
	//       Inclusion of system certificates should be done by copying from x509.SystemCertPool(),
	//       with any custom certificates appended.
	LoadClientCA(context.Context) (*x509.CertPool, error)

	// LoadRootCA returns a CertPool which should be used by clients to
	// validate server certificates.
	// NOTE: The pool returned here will be the only pool used to validate certificates.
	//       Inclusion of system certificates should be done by copying from x509.SystemCertPool(),
	//       with any custom certificates appended.
	LoadRootCA(context.Context) (*x509.CertPool, error)

	// LoadClientCertificates returns the certificate that should be presented
	// by the client when connecting to a server.
	LoadClientCertificate(context.Context) (tls.Certificate, error)

	// LoadServerCertificate returns the certificate that should be presented
	// by the server to incoming clients.
	LoadServerCertificate(context.Context) (tls.Certificate, error)

	// CertRefreshed indicates if internally any of the cert data has
	// been refreshed and should be reloaded. This will depend on the
	// implementation to support but allows for dynamic refresh of certificates
	// without a server restart.
	CertsRefreshed() bool

	// GetClientCertInfo extracts client certificate information from the client certificate
	// and other sources, depending on the Certificate Loader type.
	GetClientCertInfo(context.Context, string) (*ClientCertInfo, error)
}

A CredentialsLoader loads mTLS credential data.

func Loader

func Loader(name string) (CredentialsLoader, error)

Loader returns the CredentialsLoader associated with `name` or an error if no such implementation is registered.

type MultiIdentityCredentials added in v1.59.0

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

MultiIdentityCredentials implements credentials.TransportCredentials by dynamically selecting a client certificate during the TLS handshake based on the server's CertificateRequest.AcceptableCAs. This allows a single gRPC dial to present the correct identity without retry or fallback.

Internally it delegates to credentials.NewTLS for the actual handshake, port stripping, ALPN negotiation, and TLSInfo construction. The only added behavior is certificate refresh and dynamic identity selection via GetClientCertificate.

func NewMultiIdentityCredentials added in v1.59.0

func NewMultiIdentityCredentials(identities []ClientIdentity, rootCALoader string, logger logr.Logger, recorder metrics.MetricsRecorder) (*MultiIdentityCredentials, error)

NewMultiIdentityCredentials creates a TransportCredentials that dynamically selects among the provided identities during each TLS handshake.

rootCALoader is the name of the registered CredentialsLoader whose LoadRootCA method provides the CertPool for server verification. It is reloaded on every certificate refresh so the trust roots stay current. When all identities share the same trust roots, pass any one identity's loader name. When identities have disjoint trust roots, register a loader that returns a pre-merged pool and pass its name.

All loaders (both identity loaders and rootCALoader) are resolved from the global registry once at construction. If any loader name is not registered, construction fails immediately.

func (*MultiIdentityCredentials) ClientHandshake added in v1.59.0

func (m *MultiIdentityCredentials) ClientHandshake(ctx context.Context, serverName string, rawConn net.Conn) (net.Conn, credentials.AuthInfo, error)

ClientHandshake refreshes certificates if needed, then delegates to the inner credentials.TransportCredentials built via credentials.NewTLS.

Unlike WrappedTransportCredentials.ClientHandshake, refresh errors are logged and the handshake proceeds with existing certs. In multi-identity proxy scenarios availability is more important than cert freshness — a transient loader failure should not block all outbound connections.

func (*MultiIdentityCredentials) Clone added in v1.59.0

Clone returns a deep copy of the credentials. The inner credentials.TransportCredentials is cloned via its own Clone method, preserving any OverrideServerName that was set.

func (*MultiIdentityCredentials) Info added in v1.59.0

Info delegates to the inner credentials.

func (*MultiIdentityCredentials) OverrideServerName deprecated added in v1.59.0

func (m *MultiIdentityCredentials) OverrideServerName(name string) error

OverrideServerName stores the override and delegates to the inner credentials so Info() reflects it. The stored name is re-applied whenever inner creds are rebuilt during certificate refresh.

Deprecated: gRPC no longer calls OverrideServerName on credentials. Callers should use grpc.WithAuthority instead. This method is kept for interface compliance and for WrappedTransportCredentials parity (see mtls.go).

func (*MultiIdentityCredentials) ServerHandshake added in v1.59.0

ServerHandshake is not supported — MultiIdentityCredentials is client-side only.

type WrappedTransportCredentials added in v1.1.0

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

WrappedTransportCredentials wraps a credentials.TransportCredentials and monitors any access to the underlying credentials are up to date by calling CertsRefreshed before continuing.

func (*WrappedTransportCredentials) ClientHandshake added in v1.1.0

ClientHandshake -- see credentials.ClientHandshake

func (*WrappedTransportCredentials) Clone added in v1.1.0

Clone -- see credentials.Clone

func (*WrappedTransportCredentials) Info added in v1.1.0

Info -- see credentials.Info

func (*WrappedTransportCredentials) OverrideServerName added in v1.1.0

func (w *WrappedTransportCredentials) OverrideServerName(s string) error

OverrideServerName -- see credentials.OverrideServerName

func (*WrappedTransportCredentials) ServerHandshake added in v1.1.0

ServerHandshake -- see credentials.ServerHandshake

Directories

Path Synopsis
Package flags provides flag support for loading client/server certs and CA root of trust.
Package flags provides flag support for loading client/server certs and CA root of trust.

Jump to

Keyboard shortcuts

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