advancedtls

package module
Version: v0.0.0-...-755bf5a Latest Latest
Warning

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

Go to latest
Published: Jun 24, 2022 License: Apache-2.0 Imports: 24 Imported by: 5

Documentation

Overview

Package advancedtls is a utility library containing functions to construct credentials.TransportCredentials that can perform credential reloading and custom verification check.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckChainRevocation

func CheckChainRevocation(verifiedChains [][]*x509.Certificate, cfg RevocationConfig) error

CheckChainRevocation checks the verified certificate chain for revoked certificates based on RFC5280.

func CheckRevocation

func CheckRevocation(conn tls.ConnectionState, cfg RevocationConfig) error

CheckRevocation checks the connection for revoked certificates based on RFC5280. This implementation has the following major limitations:

* Indirect CRL files are not supported.
* CRL loading is only supported from directories in the X509_LOOKUP_hash_dir format.
* OnlySomeReasons is not supported.
* Delta CRL files are not supported.
* Certificate CRLDistributionPoint must be URLs, but are then ignored and converted into a file path.
* CRL checks are done after path building, which goes against RFC4158.

func NewClientCreds

NewClientCreds uses ClientOptions to construct a TransportCredentials based on TLS.

func NewServerCreds

NewServerCreds uses ServerOptions to construct a TransportCredentials based on TLS.

Types

type Cache

type Cache interface {
	// Add adds a value to the cache.
	Add(key, value interface{}) bool
	// Get looks up a key's value from the cache.
	Get(key interface{}) (value interface{}, ok bool)
}

Cache is an interface to cache CRL files. The cache implementation must be concurrency safe. A fixed size lru cache from golang-lru is recommended.

type ClientOptions

type ClientOptions struct {
	// IdentityOptions is OPTIONAL on client side. This field only needs to be
	// set if mutual authentication is required on server side.
	IdentityOptions IdentityCertificateOptions
	// VerifyPeer 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 VType.
	VerifyPeer CustomVerificationFunc
	// ServerNameOverride is for testing only. If set to a non-empty string,
	// it will override the virtual host name of authority (e.g. :authority
	// header field) in requests.
	ServerNameOverride string
	// RootOptions is OPTIONAL on client side. If not set, we will try to use the
	// default trust certificates in users' OS system.
	RootOptions RootCertificateOptions
	// VType is the verification type on the client side.
	VType VerificationType
	// RevocationConfig is the configurations for certificate revocation checks.
	// It could be nil if such checks are not needed.
	RevocationConfig *RevocationConfig
}

ClientOptions contains the fields needed to be filled by the client.

type CustomVerificationFunc

type CustomVerificationFunc func(params *VerificationFuncParams) (*VerificationResults, error)

CustomVerificationFunc is the function defined by users to perform custom verification check. CustomVerificationFunc returns nil if the authorization fails; otherwise returns an empty struct.

type GetRootCAsParams

type GetRootCAsParams struct {
	RawConn  net.Conn
	RawCerts [][]byte
}

GetRootCAsParams contains the parameters available to users when implementing GetRootCAs.

type GetRootCAsResults

type GetRootCAsResults struct {
	TrustCerts *x509.CertPool
}

GetRootCAsResults contains the results of GetRootCAs. If users want to reload the root trust certificate, it is required to return the proper TrustCerts in GetRootCAs.

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 MUST be set on 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 MUST be set on 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 option could be set.

type RevocationConfig

type RevocationConfig struct {
	// RootDir is the directory to search for CRL files.
	// Directory format must match OpenSSL X509_LOOKUP_hash_dir(3).
	RootDir string
	// AllowUndetermined controls if certificate chains with RevocationUndetermined
	// revocation status are allowed to complete.
	AllowUndetermined bool
	// Cache will store CRL files if not nil, otherwise files are reloaded for every lookup.
	Cache Cache
}

RevocationConfig contains options for CRL lookup.

type RevocationStatus

type RevocationStatus int

RevocationStatus is the revocation status for a certificate or chain.

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
)

func (RevocationStatus) String

func (s RevocationStatus) String() string

type RootCertificateOptions

type RootCertificateOptions struct {
	// If RootCACerts is set, it will be used every time when verifying
	// the peer certificates, without performing root certificate reloading.
	RootCACerts *x509.CertPool
	// If GetRootCertificates is set, it will be invoked to obtain root certs for
	// every new connection.
	GetRootCertificates func(params *GetRootCAsParams) (*GetRootCAsResults, 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 option could be set. If none of them are set, we use the system default trust certificates.

type ServerOptions

type ServerOptions struct {
	// IdentityOptions is REQUIRED on server side.
	IdentityOptions IdentityCertificateOptions
	// VerifyPeer 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 VType.
	VerifyPeer CustomVerificationFunc
	// 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 want the client to send certificates.
	RequireClientCert bool
	// VType is the verification type on the server side.
	VType VerificationType
	// RevocationConfig is the configurations for certificate revocation checks.
	// It could be nil if such checks are not needed.
	RevocationConfig *RevocationConfig
}

ServerOptions contains the fields needed to be filled by the server.

type VerificationFuncParams

type VerificationFuncParams 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 [][]*x509.Certificate
	// 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
}

VerificationFuncParams contains parameters available to users when implementing CustomVerificationFunc. The fields in this struct are read-only.

type VerificationResults

type VerificationResults struct{}

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

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
)

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