ssh

Documentation

Index

• Constants
• func ClientVersionWithFeatures(features ...string) string
• func IsFeatureSupported(clientVersion, feature string) (bool, error)
• func NewClientConn(ctx context.Context, conn net.Conn, addr string, config ClientConfig, ...) (ssh.Conn, <-chan ssh.NewChannel, <-chan *ssh.Request, error)
• func ParseClientVersion(clientVersion string) (string, []string, error)
• type Client
  • func Dial(ctx context.Context, network string, addr string, config ClientConfig, ...) (*Client, error)
  • func NewClient(ctx context.Context, conn net.Conn, addr string, config ClientConfig, ...) (*Client, error)
• type ClientConfig
  • func (c ClientConfig) IsEmpty() bool
• type NonTeleportSSHVersionError
  • func (NonTeleportSSHVersionError) Error() string
• type PublicKeyAuthConfig
  • func (c PublicKeyAuthConfig) IsEmpty() bool

Constants

const (
	// VersionPrefix is the prefix for the SSH client version string used by Teleport SSH clients.
	VersionPrefix = "SSH-2.0-Teleport"

	// DefaultClientVersion is the default SSH client identification string used by Teleport SSH clients.
	//
	// The Teleport version included in the client version string is intended for informational/debugging purposes only
	// and should NEVER be relied upon for inferring client capabilities or behavior. The presence of specific features
	// should be determined by parsing the version string for the expected feature flags. The string is not guaranteed
	// to be in any specific format, so it should not be parsed as a structured version string (e.g., semantic
	// versioning). DO NOT USE the Teleport version for any logic other than display or logging.
	DefaultClientVersion = VersionPrefix + "_" + api.Version

	// InBandMFAFeature is a flag included in the client version string to indicate support for in-band MFA (RFD 234).
	InBandMFAFeature = "mfav1"
)

Functions

func ClientVersionWithFeatures

func ClientVersionWithFeatures(features ...string) string

ClientVersionWithFeatures returns a client version string that includes the specified features. If no features are provided, it returns the default client version string.

func IsFeatureSupported

func IsFeatureSupported(clientVersion, feature string) (bool, error)

IsFeatureSupported checks if the given SSH client version string indicates support for the specified feature.

func NewClientConn

func NewClientConn(
	ctx context.Context,
	conn net.Conn,
	addr string,
	config ClientConfig,
	opts ...tracing.Option,
) (ssh.Conn, <-chan ssh.NewChannel, <-chan *ssh.Request, error)

NewClientConn creates a traced SSH client connection over an existing connection using the client config.

Timeout behavior is determined by [ClientConfig.Timeout]:

• If Timeout > 0, the SSH handshake respects the earlier of the context deadline or Timeout.
• If Timeout == 0, the SSH handshake uses Teleport's default I/O timeout.
• If Timeout < 0, the SSH handshake only respects the context deadline or cancellation.

func ParseClientVersion

func ParseClientVersion(clientVersion string) (string, []string, error)

ParseClientVersion parses the given SSH client version string and extracts the Teleport version and supported features. It returns the Teleport version and a slice of supported features. If no features are specified, the features slice will be nil. If the client version string does not have the expected Teleport prefix, it returns a NonTeleportSSHVersionError. If the client version string contains invalid characters, it returns a BadParameter error.

It intentionally does not attempt to parse the Teleport version into a structured format, as the Teleport version string is primarily used for informational purposes and may include additional metadata in the future. It is also intentional that features may contain spaces.

Accepted formats are:
 - SSH-2.0-Teleport_<teleport_version>
 - SSH-2.0-Teleport_<teleport_version> <feature1,feature2,...>

Types

type Client

type Client = tracessh.Client

Client is a thin wrapper around tracessh.Client.

func Dial

func Dial(
	ctx context.Context,
	network string,
	addr string,
	config ClientConfig,
	opts ...tracing.Option,
) (*Client, error)

Dial dials an SSH server using the client config.

func NewClient

func NewClient(
	ctx context.Context,
	conn net.Conn,
	addr string,
	config ClientConfig,
	opts ...tracing.Option,
) (*Client, error)

NewClient creates a traced SSH client over an existing connection using the client config.

Timeout behavior is determined by [ClientConfig.Timeout]:

• If Timeout > 0, the SSH handshake respects the earlier of the context deadline or Timeout.
• If Timeout == 0, the SSH handshake uses Teleport's default I/O timeout.
• If Timeout < 0, the SSH handshake only respects the context deadline or cancellation.

type ClientConfig

type ClientConfig struct {
	// Config contains configuration data common to both ServerConfig and ClientConfig.
	SSHConfig ssh.Config

	// User contains the username to authenticate as.
	User string

	// PublicKeyAuth configures the required public-key authentication method.
	PublicKeyAuth PublicKeyAuthConfig

	// HostKeyCallback validates the server host key during the SSH handshake.
	HostKeyCallback ssh.HostKeyCallback

	// BannerCallback displays server banners during the SSH handshake.
	BannerCallback ssh.BannerCallback

	// HostKeyAlgorithms lists the accepted server host key algorithms in order of preference.
	HostKeyAlgorithms []string

	// Timeout is the maximum amount of time to wait for the underlying TCP connection to establish. If zero, Teleport's
	// default I/O timeout is used. Negative values are preserved.
	Timeout time.Duration
}

ClientConfig defines all client-side parameters required to establish and authenticate an SSH connection with Teleport. The minimal set of required parameters is User, HostKeyCallback, and PublicKeyAuth.Signers. The rest are optional parameters that can be used to customize the SSH connection behavior. The client version string sent during the SSH handshake is determined based on how the fields are set, with the default being DefaultClientVersion if no features are indicated.

func (ClientConfig) IsEmpty

func (c ClientConfig) IsEmpty() bool

IsEmpty() returns true if the config does not have any effective values.

type NonTeleportSSHVersionError

type NonTeleportSSHVersionError struct{}

NonTeleportSSHVersionError is returned by ParseClientVersion when the provided SSH client version string does not have the expected Teleport prefix. The client is either not a Teleport client or is an older Teleport version that did not set a client version string.

func (NonTeleportSSHVersionError) Error

func (NonTeleportSSHVersionError) Error() string

Error returns the error message for NonTeleportSSHVersionError.

type PublicKeyAuthConfig

type PublicKeyAuthConfig struct {
	// Signers dynamically returns signers for public-key authentication.
	Signers func() ([]ssh.Signer, error)
}

PublicKeyAuthConfig configures the public-key authentication method used by a Teleport SSH client.

func (PublicKeyAuthConfig) IsEmpty

func (c PublicKeyAuthConfig) IsEmpty() bool

IsEmpty returns true if the PublicKeyAuthConfig does not have an effective Signers function set.