proxy

Documentation

Index

• func TestClientTlsConfig(t *testing.T, authzToken string, opt ...Option) *tls.Config
• type ClientProxy
  • func New(ctx context.Context, authzToken string, opt ...Option) (*ClientProxy, error)
  • func (p *ClientProxy) ConnectionsLeft() int32
  • func (p *ClientProxy) ListenerAddress(ctx context.Context) string
  • func (p *ClientProxy) SessionCreatedTime() time.Time
  • func (p *ClientProxy) SessionExpiration() time.Time
  • func (p *ClientProxy) Start() (retErr error)
• type Credentials
  • func ParseCredentials(creds []*targets.SessionCredential) (Credentials, error)
  • func (c Credentials) UnconsumedSessionCredentials() []*targets.SessionCredential
• type Option
  • func WithConnectionsLeftCh(with chan int32) Option
  • func WithListenAddrPort(with netip.AddrPort) Option
  • func WithListener(with net.Listener) Option
  • func WithSessionAuthorizationData(with *targets.SessionAuthorizationData) Option
  • func WithSkipSessionTeardown(with bool) Option
  • func WithWorkerHost(with string) Option
• type Options
• type SshPrivateKey
• type UsernamePassword

Functions

func TestClientTlsConfig

func TestClientTlsConfig(t *testing.T, authzToken string, opt ...Option) *tls.Config

TestClientTlsConfig is designed to allow tests to obtain the TLS configuration that would be used by the proxy in order to make specific calls to workers during tests.

Types

type ClientProxy

type ClientProxy struct {
	// contains filtered or unexported fields
}

func New

func New(ctx context.Context, authzToken string, opt ...Option) (*ClientProxy, error)

New creates a new client proxy. The given context should be cancelable; once the proxy is started, cancel the context to stop the proxy. The proxy may also cancel on its own if the session expires or there are no connections left.

Supported options:

* WithListenAddrPort - Specify a TCP address and port on which to listen

* WithListener - Specify a custom listener on which to accept connections; overrides WithListenAddrPort if both are set

* WithSessionAuthorizationData - Specify an already-unmarshaled session authorization object. If set, authzToken can be empty.

* WithConnectionsLeftCh - Specify a channel on which to send the number of remaining connections as they are consumed

* WithWorkerHost - If set, use this host name as the SNI host when making the TLS connection to the worker

EXPERIMENTAL: While this API is not expected to change, it is new and feedback from users may necessitate changes.

func (*ClientProxy) ConnectionsLeft

func (p *ClientProxy) ConnectionsLeft() int32

ConnectionsLeft returns the number of connections left in the session, or -1 if unlimited.

EXPERIMENTAL: While this API is not expected to change, it is new and feedback from users may necessitate changes.

func (*ClientProxy) ListenerAddress

func (p *ClientProxy) ListenerAddress(ctx context.Context) string

ListenerAddress returns the address of the client proxy listener. Because the listener is started with Start(), this could be called before listening occurs. To avoid returning until we have a valid value, pass a context; canceling the context will cause the function to return an empty AddrPort if it's not yet known. Otherwise the function will return when the address is available. In either case, test the result to ensure it's not empty.

Warning: a non-cancelable context will cause this call to block forever until the listener's address can be determined.

EXPERIMENTAL: While this API is not expected to change, it is new and feedback from users may necessitate changes.

func (*ClientProxy) SessionCreatedTime

func (p *ClientProxy) SessionCreatedTime() time.Time

SessionCreatedTime returns the creation time of the session

EXPERIMENTAL: While this API is not expected to change, it is new and feedback from users may necessitate changes.

func (*ClientProxy) SessionExpiration

func (p *ClientProxy) SessionExpiration() time.Time

SessionExpiration returns the expiration time of the session

EXPERIMENTAL: While this API is not expected to change, it is new and feedback from users may necessitate changes.

func (*ClientProxy) Start

func (p *ClientProxy) Start() (retErr error)

Start starts the listener for client proxying. It ends, with any errors, when the listener is closed and no connections are left. Cancel the client's proxy to force this to happen early. It is not safe to call Start twice, including once it has exited, and will immediately error in this case; create a new ClientProxy with New().

Note: if a custom listener implementation is used and the implementation can return a Temporary error, the listener will not be closed on that condition and no feedback will be given. It is up to the listener implementation to inform the client, if needed, of any status causing a Temporary error to be returned on accept.

EXPERIMENTAL: While this API is not expected to change, it is new and feedback from users may necessitate changes.

type Credentials

type Credentials struct {
	UsernamePassword []UsernamePassword
	SshPrivateKey    []SshPrivateKey
	// Unspecified are credentials that do not match one of the types above
	Unspecified []*targets.SessionCredential
}

func ParseCredentials

func ParseCredentials(creds []*targets.SessionCredential) (Credentials, error)

func (Credentials) UnconsumedSessionCredentials

func (c Credentials) UnconsumedSessionCredentials() []*targets.SessionCredential

type Option

type Option func(*Options) error

Option is a function that takes in an options struct and sets values or returns an error

func WithConnectionsLeftCh

func WithConnectionsLeftCh(with chan int32) Option

WithConnectionsLeftCh allows providing a channel to receive updates about how many connections are left. It is the caller's responsibility to ensure that this is drained and does not block.

func WithListenAddrPort

func WithListenAddrPort(with netip.AddrPort) Option

WithListenAddrPort allows overriding an address to listen on. Mutually exclusive with WithListener; that option will take precedence. If you do not want a TCP connection you must use WithListener.

func WithListener

func WithListener(with net.Listener) Option

WithListener allows passing a listener on which to accept connections. If this and WithListenAddrPort are both specified, this will take precedence.

func WithSessionAuthorizationData

func WithSessionAuthorizationData(with *targets.SessionAuthorizationData) Option

WithSessionAuthorizationData can be used to provide already-unmarshaled session authorization instead of a string token.

func WithSkipSessionTeardown

func WithSkipSessionTeardown(with bool) Option

WithSkipSessionTeardown can be used to override the normal behavior of the session sending a teardown request to the worker on completion. This is useful if you know that this will result in an error (for instance, if the worker is going to be offline) and want to avoid the attempted connection or avoid the error rather than ignore it.

func WithWorkerHost

func WithWorkerHost(with string) Option

WithWorkerHost can be used to override the worker host read from the session authorization data. This can be used to override the SNI value in the client TLS configuration and is mostly useful for tests.

type Options

type Options struct {
	WithListener                 net.Listener
	WithListenAddrPort           netip.AddrPort
	WithConnectionsLeftCh        chan int32
	WithWorkerHost               string
	WithSessionAuthorizationData *targets.SessionAuthorizationData
	WithSkipSessionTeardown      bool
}

Options contains various options. The values are exported since the options are parsed in various other packages.

type SshPrivateKey

type SshPrivateKey struct {
	Username   string `mapstructure:"username"`
	PrivateKey string `mapstructure:"private_key"`
	Passphrase string `mapstructure:"private_key_passphrase"`

	Raw *targets.SessionCredential
	// Consumed can be set by the caller to indicate that the credential has
	// been used, e.g. displayed to the user
	Consumed bool
}

SshPrivateKey contains the username and private key with optional passphrase for the key

type UsernamePassword

type UsernamePassword struct {
	Username string `mapstructure:"username"`
	Password string `mapstructure:"password"`

	Raw *targets.SessionCredential
	// Consumed can be set by the caller to indicate that the credential has
	// been used, e.g. displayed to the user
	Consumed bool
}

UsernamePassword contains username and password credentials