Documentation
¶
Overview ¶
Package mtls facilitates Mutual TLS authentication for SansShell.
Index ¶
- func LoadClientCredentials(ctx context.Context, loaderName string) (credentials.TransportCredentials, error)
- func LoadClientTLS(clientCertFile, clientKeyFile string, CAPool *x509.CertPool) (credentials.TransportCredentials, error)
- func LoadRootOfTrust(path string) (*x509.CertPool, error)
- func LoadServerCredentials(ctx context.Context, loaderName string) (credentials.TransportCredentials, error)
- func LoadServerCredentialsWithForceRefresh(ctx context.Context, loaderName string) (credentials.TransportCredentials, func() error, error)
- func LoadServerTLS(clientCertFile, clientKeyFile string, CAPool *x509.CertPool) (credentials.TransportCredentials, error)
- func Loaders() []string
- func NewClientCredentials(cert tls.Certificate, CAPool *x509.CertPool) credentials.TransportCredentials
- func NewServerCredentials(cert tls.Certificate, CAPool *x509.CertPool) credentials.TransportCredentials
- func Register(name string, loader CredentialsLoader) error
- type ClientCertInfo
- type ClientIdentity
- type CredentialsLoader
- type MultiIdentityCredentials
- func (m *MultiIdentityCredentials) ClientHandshake(ctx context.Context, serverName string, rawConn net.Conn) (net.Conn, credentials.AuthInfo, error)
- func (m *MultiIdentityCredentials) Clone() credentials.TransportCredentials
- func (m *MultiIdentityCredentials) Info() credentials.ProtocolInfo
- func (m *MultiIdentityCredentials) OverrideServerName(name string) errordeprecated
- func (m *MultiIdentityCredentials) ServerHandshake(net.Conn) (net.Conn, credentials.AuthInfo, error)
- type WrappedTransportCredentials
- func (w *WrappedTransportCredentials) ClientHandshake(ctx context.Context, s string, n net.Conn) (net.Conn, credentials.AuthInfo, error)
- func (w *WrappedTransportCredentials) Clone() credentials.TransportCredentials
- func (w *WrappedTransportCredentials) Info() credentials.ProtocolInfo
- func (w *WrappedTransportCredentials) OverrideServerName(s string) error
- func (w *WrappedTransportCredentials) ServerHandshake(n net.Conn) (net.Conn, credentials.AuthInfo, error)
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 ¶
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
func (m *MultiIdentityCredentials) Clone() credentials.TransportCredentials
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
func (m *MultiIdentityCredentials) Info() credentials.ProtocolInfo
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
func (m *MultiIdentityCredentials) ServerHandshake(net.Conn) (net.Conn, credentials.AuthInfo, error)
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
func (w *WrappedTransportCredentials) ClientHandshake(ctx context.Context, s string, n net.Conn) (net.Conn, credentials.AuthInfo, error)
ClientHandshake -- see credentials.ClientHandshake
func (*WrappedTransportCredentials) Clone ¶ added in v1.1.0
func (w *WrappedTransportCredentials) Clone() credentials.TransportCredentials
Clone -- see credentials.Clone
func (*WrappedTransportCredentials) Info ¶ added in v1.1.0
func (w *WrappedTransportCredentials) Info() credentials.ProtocolInfo
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
func (w *WrappedTransportCredentials) ServerHandshake(n net.Conn) (net.Conn, credentials.AuthInfo, error)
ServerHandshake -- see credentials.ServerHandshake