advancedtls

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2024 License: Apache-2.0 Imports: 20 Imported by: 18

Documentation

Overview

Package advancedtls provides gRPC transport credentials that allow easy configuration of advanced TLS features. The APIs here give the user more customizable control to fit their security landscape, thus the "advanced" moniker. This package provides both interfaces and generally useful implementations of those interfaces, for example periodic credential reloading, support for certificate revocation lists, and customizable certificate verification behaviors. If the provided implementations do not fit a given use case, a custom implementation of the interface can be injected.

Index

Constants

View Source 
const (
	// RevocationUndetermined means we couldn't find or verify a CRL for the cert.
	RevocationUndetermined revocationStatus = iota
	// RevocationUnrevoked means we found the CRL for the cert and the cert is not revoked.
	RevocationUnrevoked
	// RevocationRevoked means we found the CRL and the cert is revoked.
	RevocationRevoked
)

Variables

This section is empty.

Functions

func NewClientCreds 

func NewClientCreds(o *Options) (credentials.TransportCredentials, error)

NewClientCreds uses ClientOptions to construct a TransportCredentials based on TLS.

func NewServerCreds 

func NewServerCreds(o *Options) (credentials.TransportCredentials, error)

NewServerCreds uses ServerOptions to construct a TransportCredentials based on TLS.

Types

type CRL 

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

CRL contains a pkix.CertificateList and parsed extensions that aren't provided by the golang CRL parser. All CRLs should be loaded using NewCRL() for bytes directly or ReadCRLFile() to read directly from a filepath

func NewCRL 

func NewCRL(b []byte) (*CRL, error)

NewCRL constructs new CRL from the provided byte array.

func ReadCRLFile 

func ReadCRLFile(path string) (*CRL, error)

ReadCRLFile reads a file from the provided path, and returns constructed CRL struct from it.

type CRLProvider 

type CRLProvider interface {
	// CRL accepts x509 Cert and returns a related CRL struct, which can contain
	// either an empty or non-empty list of revoked certificates. If an error is
	// thrown or (nil, nil) is returned, it indicates that we can't load any
	// authoritative CRL files (which may not necessarily be a problem). It's not
	// considered invalid to have no CRLs if there are no revocations for an
	// issuer. In such cases, the status of the check CRL operation is marked as
	// RevocationUndetermined, as defined in [RFC5280 - Undetermined].
	//
	// [RFC5280 - Undetermined]: https://datatracker.ietf.org/doc/html/rfc5280#section-6.3.3
	CRL(cert *x509.Certificate) (*CRL, error)
}

CRLProvider is the interface to be implemented to enable custom CRL provider behavior, as defined in gRFC A69.

The interface defines how gRPC gets CRLs from the provider during handshakes, but doesn't prescribe a specific way to load and store CRLs. Such implementations can be used in RevocationOptions of advancedtls.ClientOptions and/or advancedtls.ServerOptions. Please note that checking CRLs is directly on the path of connection establishment, so implementations of the CRL function need to be fast, and slow things such as file IO should be done asynchronously.

type CertificateChains 

type CertificateChains [][]*x509.Certificate

type ConnectionInfo 

type ConnectionInfo struct {
	// RawConn is the raw net.Conn representing a connection.
	RawConn net.Conn
	// RawCerts is the byte representation of the presented peer cert chain.
	RawCerts [][]byte
}

ConnectionInfo contains the parameters available to users when implementing GetRootCertificates.

type FileWatcherCRLProvider 

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

FileWatcherCRLProvider implements the CRLProvider interface by periodically scanning CRLDirectory (see FileWatcherOptions) and storing CRL structs in-memory. Users should call Close to stop the background refresh of CRLDirectory.

func NewFileWatcherCRLProvider 

func NewFileWatcherCRLProvider(o FileWatcherOptions) (*FileWatcherCRLProvider, error)

NewFileWatcherCRLProvider returns a new instance of the FileWatcherCRLProvider. It uses FileWatcherOptions to validate and apply configuration required for creating a new instance. The initial scan of CRLDirectory is performed inside this function. Users should call Close to stop the background refresh of CRLDirectory.

func (*FileWatcherCRLProvider) CRL 

func (p *FileWatcherCRLProvider) CRL(cert *x509.Certificate) (*CRL, error)

CRL retrieves the CRL associated with the given certificate's issuer DN from in-memory if it was loaded during FileWatcherOptions.CRLDirectory scan before the execution of this function.

func (*FileWatcherCRLProvider) Close 

func (p *FileWatcherCRLProvider) Close()

Close waits till the background refresh of CRLDirectory of FileWatcherCRLProvider is done and then stops it.

type FileWatcherOptions 

type FileWatcherOptions struct {
	CRLDirectory               string          // Required: Path of the directory containing CRL files
	RefreshDuration            time.Duration   // Optional: Time interval (default 1 hour) between CRLDirectory scans, can't be smaller than 1 minute
	CRLReloadingFailedCallback func(err error) // Optional: Custom callback executed when a CRL file can’t be processed
}

FileWatcherOptions represents a data structure holding a configuration for FileWatcherCRLProvider.

type HandshakeVerificationInfo 

type HandshakeVerificationInfo struct {
	// The target server name that the client connects to when establishing the
	// connection. This field is only meaningful for client side. On server side,
	// this field would be an empty string.
	ServerName string
	// The raw certificates sent from peer.
	RawCerts [][]byte
	// The verification chain obtained by checking peer RawCerts against the
	// trust certificate bundle(s), if applicable.
	VerifiedChains CertificateChains
	// The leaf certificate sent from peer, if choosing to verify the peer
	// certificate(s) and that verification passed. This field would be nil if
	// either user chose not to verify or the verification failed.
	Leaf *x509.Certificate
}

HandshakeVerificationInfo contains information about a handshake needed for verification for use when implementing the `PostHandshakeVerificationFunc` The fields in this struct are read-only.

type IdentityCertificateOptions 

type IdentityCertificateOptions struct {
	// If Certificates is set, it will be used every time when needed to present
	// identity certificates, without performing identity certificate reloading.
	Certificates []tls.Certificate
	// If GetIdentityCertificatesForClient is set, it will be invoked to obtain
	// identity certs for every new connection.
	// This field is only relevant when set on the client side.
	GetIdentityCertificatesForClient func(*tls.CertificateRequestInfo) (*tls.Certificate, error)
	// If GetIdentityCertificatesForServer is set, it will be invoked to obtain
	// identity certs for every new connection.
	// This field is only relevant when set on the server side.
	GetIdentityCertificatesForServer func(*tls.ClientHelloInfo) ([]*tls.Certificate, error)
	// If IdentityProvider is set, we will use the identity certs from the
	// Provider's KeyMaterial() call in the new connections. The Provider must
	// have initial credentials if specified. Otherwise, KeyMaterial() will block
	// forever.
	IdentityProvider certprovider.Provider
}

IdentityCertificateOptions contains options to obtain identity certificates for both the client and the server. At most one field should be set. Setting more than one field will result in undefined behavior.

type Options 

type Options struct {
	// IdentityOptions is OPTIONAL on client side. This field only needs to be
	// set if mutual authentication is required on server side.
	// IdentityOptions is REQUIRED on server side.
	IdentityOptions IdentityCertificateOptions
	// AdditionalPeerVerification is a custom verification check after certificate signature
	// check.
	// If this is set, we will perform this customized check after doing the
	// normal check(s) indicated by setting VerificationType.
	AdditionalPeerVerification PostHandshakeVerificationFunc
	// RootOptions is OPTIONAL on server side. This field only needs to be set if
	// mutual authentication is required(RequireClientCert is true).
	RootOptions RootCertificateOptions
	// If the server requires the client to send certificates. This value is only
	// relevant when configuring options for the server. Is not used for
	// client-side configuration.
	RequireClientCert bool
	// VerificationType defines what type of peer verification is done. See
	// the `VerificationType` enum for the different options.
	// Default: CertAndHostVerification
	VerificationType VerificationType
	// RevocationOptions is the configurations for certificate revocation checks.
	// It could be nil if such checks are not needed.
	RevocationOptions *RevocationOptions
	// MinTLSVersion contains the minimum TLS version that is acceptable.
	// The value should be set using tls.VersionTLSxx from https://pkg.go.dev/crypto/tls
	// By default, TLS 1.2 is currently used as the minimum when acting as a
	// client, and TLS 1.0 when acting as a server. TLS 1.0 is the minimum
	// supported by this package, both as a client and as a server.  This
	// default may be changed over time affecting backwards compatibility.
	MinTLSVersion uint16
	// MaxTLSVersion contains the maximum TLS version that is acceptable.
	// The value should be set using tls.VersionTLSxx from https://pkg.go.dev/crypto/tls
	// By default, the maximum version supported by this package is used,
	// which is currently TLS 1.3.  This default may be changed over time
	// affecting backwards compatibility.
	MaxTLSVersion uint16
	// CipherSuites is an unordered list of supported TLS 1.0–1.2
	// ciphersuites. TLS 1.3 ciphersuites are not configurable. If nil, a
	// safe default list is used.
	CipherSuites []uint16
	// contains filtered or unexported fields
}

Options contains the fields a user can configure when setting up TLS clients and servers

type PostHandshakeVerificationFunc 

type PostHandshakeVerificationFunc func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults, error)

PostHandshakeVerificationFunc is the function defined by users to perform custom verification checks after chain building and regular handshake verification has been completed. PostHandshakeVerificationFunc should return (nil, error) if the authorization should fail, with the error containing information on why it failed.

type PostHandshakeVerificationResults 

type PostHandshakeVerificationResults struct{}

PostHandshakeVerificationResults contains the information about results of PostHandshakeVerificationFunc. PostHandshakeVerificationResults is an empty struct for now. It may be extended in the future to include more information.

type RevocationOptions 

type RevocationOptions struct {
	// DenyUndetermined controls if certificate chains with RevocationUndetermined
	// revocation status are allowed to complete.
	DenyUndetermined bool
	// CRLProvider is an alternative to using RootDir directly for the
	// X509_LOOKUP_hash_dir approach to CRL files. If set, the CRLProvider's CRL
	// function will be called when looking up and fetching CRLs during the
	// handshake.
	CRLProvider CRLProvider
}

RevocationOptions allows a user to configure certificate revocation behavior.

type RootCertificateOptions 

type RootCertificateOptions struct {
	// If RootCertificates is set, it will be used every time when verifying
	// the peer certificates, without performing root certificate reloading.
	RootCertificates *x509.CertPool
	// If GetRootCertificates is set, it will be invoked to obtain root certs for
	// every new connection.
	GetRootCertificates func(params *ConnectionInfo) (*RootCertificates, error)
	// If RootProvider is set, we will use the root certs from the Provider's
	// KeyMaterial() call in the new connections. The Provider must have initial
	// credentials if specified. Otherwise, KeyMaterial() will block forever.
	RootProvider certprovider.Provider
}

RootCertificateOptions contains options to obtain root trust certificates for both the client and the server. At most one field should be set. If none of them are set, we use the system default trust certificates. Setting more than one field will result in undefined behavior.

type RootCertificates 

type RootCertificates struct {
	// TrustCerts is the pool of trusted certificates.
	TrustCerts *x509.CertPool
}

RootCertificates is the result of GetRootCertificates. If users want to reload the root trust certificate, it is required to return the proper TrustCerts in GetRootCAs.

type StaticCRLProvider 

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

StaticCRLProvider implements CRLProvider interface by accepting raw content of CRL files at creation time and storing parsed CRL structs in-memory.

func NewStaticCRLProvider 

func NewStaticCRLProvider(rawCRLs [][]byte) *StaticCRLProvider

NewStaticCRLProvider processes raw content of CRL files, adds parsed CRL structs into in-memory, and returns a new instance of the StaticCRLProvider.

func (*StaticCRLProvider) CRL 

func (p *StaticCRLProvider) CRL(cert *x509.Certificate) (*CRL, error)

CRL returns CRL struct if it was passed to NewStaticCRLProvider.

type VerificationType 

type VerificationType int

VerificationType is the enum type that represents different levels of verification users could set, both on client side and on server side. 

const (
	// CertAndHostVerification indicates doing both certificate signature check
	// and hostname check.
	CertAndHostVerification VerificationType = iota
	// CertVerification indicates doing certificate signature check only. Setting
	// this field without proper custom verification check would leave the
	// application susceptible to the MITM attack.
	CertVerification
	// SkipVerification indicates skipping both certificate signature check and
	// hostname check. If setting this field, proper custom verification needs to
	// be implemented in order to complete the authentication. Setting this field
	// with a nil custom verification would raise an error.
	SkipVerification
)

Source Files

View all Source files

Directories

Path Synopsis
examples module
internal
testutils
Package testutils contains helper functions for advancedtls.
 Package testutils contains helper functions for advancedtls.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.