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

                            Directories

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