fallback

Documentation

Overview

Package fallback provides default implementations of fallback options when S2A fails.

Index

• Variables
• func DefaultFallbackDialerAndAddress(fallbackAddr string) (*tls.Dialer, string, error)
• type ClientHandshake
  • func DefaultFallbackClientHandshakeFunc(fallbackAddr string) (ClientHandshake, error)

Variables

var FallbackTLSConfigGRPC = tls.Config{
	MinVersion:         tls.VersionTLS13,
	ClientSessionCache: nil,
	NextProtos:         []string{alpnProtoStrH2},
}

FallbackTLSConfigGRPC is a tls.Config used by the DefaultFallbackClientHandshakeFunc function. It supports GRPC use case, thus the alpn is set to 'h2'.

var FallbackTLSConfigHTTP = tls.Config{
	MinVersion:         tls.VersionTLS13,
	ClientSessionCache: nil,
	NextProtos:         []string{alpnProtoStrH2, alpnProtoStrHTTP},
}

FallbackTLSConfigHTTP is a tls.Config used by the DefaultFallbackDialerAndAddress func. It supports the HTTP use case and the alpn is set to both 'http/1.1' and 'h2'.

Functions

func DefaultFallbackDialerAndAddress

func DefaultFallbackDialerAndAddress(fallbackAddr string) (*tls.Dialer, string, error)

DefaultFallbackDialerAndAddress returns a TLS dialer and the network address to dial. Example use:

    fallbackDialer, fallbackServerAddr := fallback.DefaultFallbackDialerAndAddress(fallbackAddr)
	dialTLSContext := s2a.NewS2aDialTLSContextFunc(&s2a.ClientOptions{
		S2AAddress:         s2aAddress, // required
		FallbackOpts: &s2a.FallbackOptions{
			FallbackDialer: &s2a.FallbackDialer{
				Dialer:     fallbackDialer,
				ServerAddr: fallbackServerAddr,
			},
		},
})

The fallback server's certificate should be verifiable using OS root store. The fallbackAddr is expected to be a network address, e.g. example.com:port. If port is not specified, it uses default port 443. In the returned function's TLS config, ClientSessionCache is explicitly set to nil to disable TLS resumption, and min TLS version is set to 1.3.

Types

type ClientHandshake

type ClientHandshake func(ctx context.Context, targetServer string, conn net.Conn, err error) (net.Conn, credentials.AuthInfo, error)

ClientHandshake establishes a TLS connection and returns it, plus its auth info. Inputs:

targetServer: the server attempted with S2A.
conn: the tcp connection to the server at address targetServer that was passed into S2A's ClientHandshake func.
            If fallback is successful, the `conn` should be closed.
err: the error encountered when performing the client-side TLS handshake with S2A.

func DefaultFallbackClientHandshakeFunc

func DefaultFallbackClientHandshakeFunc(fallbackAddr string) (ClientHandshake, error)

DefaultFallbackClientHandshakeFunc returns a ClientHandshake function, which establishes a TLS connection to the provided fallbackAddr, returns the new connection and its auth info. Example use:

transportCreds, _ = s2a.NewClientCreds(&s2a.ClientOptions{
	S2AAddress: s2aAddress,
	FallbackOpts: &s2a.FallbackOptions{ // optional
		FallbackClientHandshakeFunc: fallback.DefaultFallbackClientHandshakeFunc(fallbackAddr),
	},
})

The fallback server's certificate must be verifiable using OS root store. The fallbackAddr is expected to be a network address, e.g. example.com:port. If port is not specified, it uses default port 443. In the returned function's TLS config, ClientSessionCache is explicitly set to nil to disable TLS resumption, and min TLS version is set to 1.3.