advancedtls

Documentation

Overview

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

Index

• func NewClientCreds(o *ClientOptions) (credentials.TransportCredentials, error)
• func NewServerCreds(o *ServerOptions) (credentials.TransportCredentials, error)
• type ClientOptions
• type CustomVerificationFunc
• type GetRootCAsParams
• type GetRootCAsResults
• type IdentityCertificateOptions
• type RootCertificateOptions
• type ServerOptions
• type VerificationFuncParams
• type VerificationResults
• type VerificationType

Functions

func NewClientCreds

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

NewClientCreds uses ClientOptions to construct a TransportCredentials based on TLS.

func NewServerCreds

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

NewServerCreds uses ServerOptions to construct a TransportCredentials based on TLS.

Types

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
}

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 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
}

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
)