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)
• func WrapSyscallConn(rawConn, newConn net.Conn) net.Conn
• type ClientOptions
• type CustomVerificationFunc
• type GetRootCAsParams
• type GetRootCAsResults
• 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.

func WrapSyscallConn

func WrapSyscallConn(rawConn, newConn net.Conn) net.Conn

WrapSyscallConn tries to wrap rawConn and newConn into a net.Conn that implements syscall.Conn. rawConn will be used to support syscall, and newConn will be used for read/write.

This function returns newConn if rawConn doesn't implement syscall.Conn.

Types

type ClientOptions

type ClientOptions struct {
	// If field Certificates is set, field GetClientCertificate will be ignored.
	// The client will use Certificates every time when asked for a certificate,
	// without performing certificate reloading.
	Certificates []tls.Certificate
	// If GetClientCertificate is set and Certificates is nil, the client will
	// invoke this function every time asked to present certificates to the
	// server when a new connection is established. This is known as peer
	// certificate reloading.
	GetClientCertificate func(*tls.CertificateRequestInfo) (*tls.Certificate, error)
	// 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
	// RootCertificateOptions is REQUIRED to be correctly set on client side.
	RootCertificateOptions
	// VType is the verification type on the client side.
	VType VerificationType
}

ClientOptions contains all the fields and functions needed to be filled by the client. General rules for certificate setting on client side: Certificates or GetClientCertificate indicates the certificates sent from the client to the server to prove client's identities. The rules for setting these two fields are: If requiring mutual authentication on server side:

Either Certificates or GetClientCertificate must be set; the other will
be ignored.

Otherwise:

Nothing needed(the two fields will be ignored).

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 RootCertificateOptions

type RootCertificateOptions struct {
	// If field RootCACerts is set, field GetRootCAs will be ignored. RootCACerts
	// will be used every time when verifying the peer certificates, without
	// performing root certificate reloading.
	RootCACerts *x509.CertPool
	// If GetRootCAs is set and RootCACerts is nil, GetRootCAs will be invoked
	// every time asked to check certificates sent from the server when a new
	// connection is established.
	// This is known as root CA certificate reloading.
	GetRootCAs func(params *GetRootCAsParams) (*GetRootCAsResults, error)
}

RootCertificateOptions contains a field and a function for obtaining root trust certificates. It is used by both ClientOptions and ServerOptions.

type ServerOptions

type ServerOptions struct {
	// If field Certificates is set, field GetClientCertificate will be ignored.
	// The server will use Certificates every time when asked for a certificate,
	// without performing certificate reloading.
	Certificates []tls.Certificate
	// If GetClientCertificate is set and Certificates is nil, the server will
	// invoke this function every time asked to present certificates to the
	// client when a new connection is established. This is known as peer
	// certificate reloading.
	GetCertificate func(*tls.ClientHelloInfo) (*tls.Certificate, error)
	// 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
	// RootCertificateOptions is only required when mutual TLS is
	// enabled(RequireClientCert is true).
	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 all the fields and functions needed to be filled by the client. General rules for certificate setting on server side: Certificates or GetClientCertificate indicates the certificates sent from the server to the client to prove server's identities. The rules for setting these two fields are: Either Certificates or GetCertificate must be set; the other will be ignored.

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
)