advancedtls
packagemodule
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
Documentation¶
Overview¶
Package advancedtls provides gRPC transport credentials that allow easyconfiguration of advanced TLS features. The APIs here give the user morecustomizable control to fit their security landscape, thus the "advanced"moniker. This package provides both interfaces and generally usefulimplementations of those interfaces, for example periodic credentialreloading, support for certificate revocation lists, and customizablecertificate verification behaviors. If the provided implementations do notfit a given use case, a custom implementation of the interface can beinjected.
Index¶
- Constants
- func NewClientCreds(o *Options) (credentials.TransportCredentials, error)
- func NewServerCreds(o *Options) (credentials.TransportCredentials, error)
- type CRL
- type CRLProvider
- type CertificateChains
- type ConnectionInfo
- type FileWatcherCRLProvider
- type FileWatcherOptions
- type HandshakeVerificationInfo
- type IdentityCertificateOptions
- type Options
- type PostHandshakeVerificationFunc
- type PostHandshakeVerificationResults
- type RevocationOptions
- type RootCertificateOptions
- type RootCertificates
- type StaticCRLProvider
- type VerificationType
Constants¶
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¶
funcNewClientCreds¶
func NewClientCreds(o *Options) (credentials.TransportCredentials,error)
NewClientCreds uses ClientOptions to construct a TransportCredentials basedon TLS.
funcNewServerCreds¶
func NewServerCreds(o *Options) (credentials.TransportCredentials,error)
NewServerCreds uses ServerOptions to construct a TransportCredentials basedon TLS.
Types¶
typeCRL¶
type CRL struct {// contains filtered or unexported fields}CRL contains a pkix.CertificateList and parsed extensions that aren'tprovided by the golang CRL parser.All CRLs should be loaded using NewCRL() for bytes directly or ReadCRLFile()to read directly from a filepath
funcReadCRLFile¶
ReadCRLFile reads a file from the provided path, and returns constructed CRLstruct from it.
typeCRLProvider¶
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.3CRL(cert *x509.Certificate) (*CRL,error)}CRLProvider is the interface to be implemented to enable custom CRL providerbehavior, as defined ingRFC 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. Suchimplementations can be used in RevocationOptions of advancedtls.ClientOptionsand/or advancedtls.ServerOptions.Please note that checking CRLs is directly on the path of connectionestablishment, so implementations of the CRL function need to be fast, andslow things such as file IO should be done asynchronously.
typeCertificateChains¶
type CertificateChains [][]*x509.Certificate
typeConnectionInfo¶
type ConnectionInfo struct {// RawConn is the raw net.Conn representing a connection.RawConnnet.Conn// RawCerts is the byte representation of the presented peer cert chain.RawCerts [][]byte}ConnectionInfo contains the parameters available to users whenimplementing GetRootCertificates.
typeFileWatcherCRLProvider¶
type FileWatcherCRLProvider struct {// contains filtered or unexported fields}FileWatcherCRLProvider implements the CRLProvider interface by periodicallyscanning CRLDirectory (see FileWatcherOptions) and storing CRL structsin-memory. Users should call Close to stop the background refresh ofCRLDirectory.
funcNewFileWatcherCRLProvider¶
func NewFileWatcherCRLProvider(oFileWatcherOptions) (*FileWatcherCRLProvider,error)
NewFileWatcherCRLProvider returns a new instance of theFileWatcherCRLProvider. It uses FileWatcherOptions to validate and applyconfiguration required for creating a new instance. The initial scan ofCRLDirectory is performed inside this function. Users should call Close tostop 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 fromin-memory if it was loaded during FileWatcherOptions.CRLDirectory scan beforethe execution of this function.
func (*FileWatcherCRLProvider)Close¶
func (p *FileWatcherCRLProvider) Close()
Close waits till the background refresh of CRLDirectory ofFileWatcherCRLProvider is done and then stops it.
typeFileWatcherOptions¶
type FileWatcherOptions struct {CRLDirectorystring// Required: Path of the directory containing CRL filesRefreshDurationtime.Duration// Optional: Time interval (default 1 hour) between CRLDirectory scans, can't be smaller than 1 minuteCRLReloadingFailedCallback func(errerror)// Optional: Custom callback executed when a CRL file can’t be processed}FileWatcherOptions represents a data structure holding a configuration forFileWatcherCRLProvider.
typeHandshakeVerificationInfo¶
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.ServerNamestring// The raw certificates sent from peer.RawCerts [][]byte// The verification chain obtained by checking peer RawCerts against the// trust certificate bundle(s), if applicable.VerifiedChainsCertificateChains// 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 forverification for use when implementing the `PostHandshakeVerificationFunc`The fields in this struct are read-only.
typeIdentityCertificateOptions¶
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.IdentityProvidercertprovider.Provider}IdentityCertificateOptions contains options to obtain identity certificatesfor both the client and the server.At most one field should be set. Setting more than one field will result in undefined behavior.
typeOptions¶
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.IdentityOptionsIdentityCertificateOptions// 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.AdditionalPeerVerificationPostHandshakeVerificationFunc// RootOptions is OPTIONAL on server side. This field only needs to be set if// mutual authentication is required(RequireClientCert is true).RootOptionsRootCertificateOptions// 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.RequireClientCertbool// VerificationType defines what type of peer verification is done. See// the `VerificationType` enum for the different options.// Default: CertAndHostVerificationVerificationTypeVerificationType// 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 fromhttps://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.MinTLSVersionuint16// MaxTLSVersion contains the maximum TLS version that is acceptable.// The value should be set using tls.VersionTLSxx fromhttps://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.MaxTLSVersionuint16// 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 clientsand servers
typePostHandshakeVerificationFunc¶
type PostHandshakeVerificationFunc func(params *HandshakeVerificationInfo) (*PostHandshakeVerificationResults,error)
PostHandshakeVerificationFunc is the function defined by users to performcustom verification checks after chain building and regular handshakeverification has been completed.PostHandshakeVerificationFunc should return (nil, error) if the authorizationshould fail, with the error containing information on why it failed.
typePostHandshakeVerificationResults¶
type PostHandshakeVerificationResults struct{}PostHandshakeVerificationResults contains the information about results ofPostHandshakeVerificationFunc.PostHandshakeVerificationResults is an empty struct for now. It may be extended in thefuture to include more information.
typeRevocationOptions¶
type RevocationOptions struct {// DenyUndetermined controls if certificate chains with RevocationUndetermined// revocation status are allowed to complete.DenyUndeterminedbool// 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.CRLProviderCRLProvider}RevocationOptions allows a user to configure certificate revocation behavior.
typeRootCertificateOptions¶
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.RootProvidercertprovider.Provider}RootCertificateOptions contains options to obtain root trust certificatesfor both the client and the server.At most one field should be set. If none of them are set, we use the systemdefault trust certificates. Setting more than one field will result inundefined behavior.
typeRootCertificates¶
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 returnthe proper TrustCerts in GetRootCAs.
typeStaticCRLProvider¶
type StaticCRLProvider struct {// contains filtered or unexported fields}StaticCRLProvider implements CRLProvider interface by accepting raw contentof CRL files at creation time and storing parsed CRL structs in-memory.
funcNewStaticCRLProvider¶
func NewStaticCRLProvider(rawCRLs [][]byte) *StaticCRLProvider
NewStaticCRLProvider processes raw content of CRL files, adds parsed CRLstructs 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.
typeVerificationType¶
type VerificationTypeint
VerificationType is the enum type that represents different levels ofverification users could set, both on client side and on server side.
const (// CertAndHostVerification indicates doing both certificate signature check// and hostname check.CertAndHostVerificationVerificationType =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
Directories