sshutils

Documentation

Overview

Package sshutils defines several functions and types used across the Teleport API and other Teleport packages when working with SSH.

Index

• Constants
• func AsAuthMethod(sshCert *ssh.Certificate, signer crypto.Signer) (ssh.AuthMethod, error)
• func HostKeyCallback(caCerts [][]byte, withHostKeyFallback bool) (ssh.HostKeyCallback, error)
• func IsSSHCertType(val string) bool
• func KeysEqual(ak, bk ssh.PublicKey) bool
• func MakeRealHostCert(realCA ssh.Signer) (ssh.Signer, error)
• func MakeSpoofedHostCert(realCA ssh.Signer) (ssh.Signer, error)
• func MakeTestSSHCA() (ssh.Signer, error)
• func NewHostKeyCallback(conf HostKeyCallbackConfig) (ssh.HostKeyCallback, error)
• func ParseAuthorizedKeys(authorizedKeys [][]byte) ([]ssh.PublicKey, error)
• func ParseCertificate(buf []byte) (*ssh.Certificate, error)
• func ParseKnownHosts(knownHosts [][]byte) ([]ssh.PublicKey, error)
• func ProxyClientSSHConfig(sshCert *ssh.Certificate, priv crypto.Signer, sshCAs ...[]byte) (*ssh.ClientConfig, error)
• func SSHSigner(sshCert *ssh.Certificate, signer crypto.Signer) (ssh.Signer, error)
• type CertChecker
  • func (c *CertChecker) Authenticate(conn ssh.ConnMetadata, key ssh.PublicKey) (*ssh.Permissions, error)
  • func (c *CertChecker) CheckCert(principal string, cert *ssh.Certificate) error
  • func (c *CertChecker) CheckHostKey(addr string, remote net.Addr, key ssh.PublicKey) error
• type ChConn
  • func ConnectProxyTransport(sconn ssh.Conn, req *DialReq, exclusive bool) (conn *ChConn, invalid bool, err error)
  • func NewChConn(conn Conn, ch ssh.Channel) *ChConn
  • func NewExclusiveChConn(conn Conn, ch ssh.Channel) *ChConn
  • func (c *ChConn) Close() error
  • func (c *ChConn) LocalAddr() net.Addr
  • func (c *ChConn) Read(data []byte) (int, error)
  • func (c *ChConn) RemoteAddr() net.Addr
  • func (c *ChConn) SetDeadline(t time.Time) error
  • func (c *ChConn) SetReadDeadline(t time.Time) error
  • func (c *ChConn) SetWriteDeadline(t time.Time) error
• type CheckersGetter
• type Conn
• type DialReq
  • func (d *DialReq) CheckAndSetDefaults() error
• type HandshakePayload
• type HostKeyCallbackConfig
  • func (c *HostKeyCallbackConfig) Check() error

Constants

const (
	// ConnectionTypeRequest is a request sent over a SSH channel that returns a
	// boolean which indicates the connection type (direct or tunnel).
	ConnectionTypeRequest = "x-teleport-connection-type"
)

const (
	// ProxyHelloSignature is a string which Teleport proxy will send
	// right after the initial SSH "handshake/version" message if it detects
	// talking to a Teleport server.
	//
	// This is also leveraged by tsh to propagate its tracing span ID.
	ProxyHelloSignature = "Teleport-Proxy"
)

Functions

func AsAuthMethod

func AsAuthMethod(sshCert *ssh.Certificate, signer crypto.Signer) (ssh.AuthMethod, error)

AsAuthMethod returns an "auth method" interface, a common abstraction used by Golang SSH library. This is how you actually use a Key to feed it into the SSH lib.

func HostKeyCallback

func HostKeyCallback(caCerts [][]byte, withHostKeyFallback bool) (ssh.HostKeyCallback, error)

HostKeyCallback returns an ssh.HostKeyCallback that validates host keys/certs against SSH CAs in the Key.

If not CAs are present in the Key, the returned ssh.HostKeyCallback is nil. This causes golang.org/x/crypto/ssh to prompt the user to verify host key fingerprint (same as OpenSSH does for an unknown host).

func IsSSHCertType

func IsSSHCertType(val string) bool

IsSSHCertType checks if the given string looks like an ssh cert type. e.g. ssh-rsa-cert-v01@openssh.com.

func KeysEqual

func KeysEqual(ak, bk ssh.PublicKey) bool

KeysEqual is constant time compare of the keys to avoid timing attacks

func MakeRealHostCert

func MakeRealHostCert(realCA ssh.Signer) (ssh.Signer, error)

MakeRealHostCert makes an SSH host certificate that is signed by the provided CA.

func MakeSpoofedHostCert

func MakeSpoofedHostCert(realCA ssh.Signer) (ssh.Signer, error)

MakeSpoofedHostCert makes an SSH host certificate that claims to be signed by the provided CA but in fact is signed by a different CA.

func MakeTestSSHCA

func MakeTestSSHCA() (ssh.Signer, error)

MakeTestSSHCA generates a new SSH certificate authority for tests.

func NewHostKeyCallback

func NewHostKeyCallback(conf HostKeyCallbackConfig) (ssh.HostKeyCallback, error)

NewHostKeyCallback returns host key callback function with the specified parameters.

func ParseAuthorizedKeys

func ParseAuthorizedKeys(authorizedKeys [][]byte) ([]ssh.PublicKey, error)

ParseAuthorizedKeys parses provided authorized_keys entries into ssh.PublicKey list.

func ParseCertificate

func ParseCertificate(buf []byte) (*ssh.Certificate, error)

ParseCertificate parses an SSH certificate from the authorized_keys format.

func ParseKnownHosts

func ParseKnownHosts(knownHosts [][]byte) ([]ssh.PublicKey, error)

ParseKnownHosts parses provided known_hosts entries into ssh.PublicKey list.

func ProxyClientSSHConfig

func ProxyClientSSHConfig(sshCert *ssh.Certificate, priv crypto.Signer, sshCAs ...[]byte) (*ssh.ClientConfig, error)

ProxyClientSSHConfig returns an ssh.ClientConfig from the given ssh.AuthMethod. If sshCAs are provided, they will be used in the config's HostKeyCallback.

The config is set up to authenticate to proxy with the first available principal.

func SSHSigner

func SSHSigner(sshCert *ssh.Certificate, signer crypto.Signer) (ssh.Signer, error)

SSHSigner returns an ssh.Signer from certificate and private key

Types

type CertChecker

type CertChecker struct {
	ssh.CertChecker

	// FIPS means in addition to checking the validity of the key or
	// certificate, also check that FIPS 140-2 algorithms were used.
	FIPS bool

	// OnCheckCert is called when validating host certificate.
	OnCheckCert func(*ssh.Certificate)
}

CertChecker is a drop-in replacement for ssh.CertChecker. In FIPS mode, checks if the certificate (or key) were generated with a supported algorithm.

func (*CertChecker) Authenticate

func (c *CertChecker) Authenticate(conn ssh.ConnMetadata, key ssh.PublicKey) (*ssh.Permissions, error)

Authenticate checks the validity of a user certificate.

func (*CertChecker) CheckCert

func (c *CertChecker) CheckCert(principal string, cert *ssh.Certificate) error

CheckCert checks certificate metadata and signature.

func (*CertChecker) CheckHostKey

func (c *CertChecker) CheckHostKey(addr string, remote net.Addr, key ssh.PublicKey) error

CheckHostKey checks the validity of a host certificate.

type ChConn

type ChConn struct {
	ssh.Channel
	// contains filtered or unexported fields
}

ChConn is a net.Conn like object that uses SSH channel

func ConnectProxyTransport

func ConnectProxyTransport(sconn ssh.Conn, req *DialReq, exclusive bool) (conn *ChConn, invalid bool, err error)

ConnectProxyTransport opens a channel over the remote tunnel and connects to the requested host.

Returns the net.Conn wrapper over an SSH channel, whether the provided ssh.Conn should be considered invalid due to errors opening or sending a request to the channel while setting up the ChConn, and any error that occurs.

func NewChConn

func NewChConn(conn Conn, ch ssh.Channel) *ChConn

NewChConn returns a new net.Conn implemented over SSH channel

func NewExclusiveChConn

func NewExclusiveChConn(conn Conn, ch ssh.Channel) *ChConn

NewExclusiveChConn returns a new net.Conn implemented over SSH channel, whenever this connection closes

func (*ChConn) Close

func (c *ChConn) Close() error

Close closes channel and if the ChConn is exclusive, connection as well

func (*ChConn) LocalAddr

func (c *ChConn) LocalAddr() net.Addr

LocalAddr returns a local address of a connection Uses underlying net.Conn implementation

func (*ChConn) Read

func (c *ChConn) Read(data []byte) (int, error)

Read reads from the channel.

func (*ChConn) RemoteAddr

func (c *ChConn) RemoteAddr() net.Addr

RemoteAddr returns a remote address of a connection Uses underlying net.Conn implementation

func (*ChConn) SetDeadline

func (c *ChConn) SetDeadline(t time.Time) error

SetDeadline sets a connection deadline.

func (*ChConn) SetReadDeadline

func (c *ChConn) SetReadDeadline(t time.Time) error

SetReadDeadline sets a connection read deadline.

func (*ChConn) SetWriteDeadline

func (c *ChConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets write deadline on a connection ignored for the channel connection

type CheckersGetter

type CheckersGetter func() ([]ssh.PublicKey, error)

CheckersGetter defines a function that returns a list of ssh public keys.

type Conn

type Conn interface {
	io.Closer
	// RemoteAddr returns the remote address for this connection.
	RemoteAddr() net.Addr
	// LocalAddr returns the local address for this connection.
	LocalAddr() net.Addr
}

type DialReq

type DialReq struct {
	// Address is the target host to make a connection to.
	Address string `json:"address,omitempty"`

	// ServerID is the hostUUID.clusterName of the node. ServerID is used when
	// dialing through a tunnel to SSH and application nodes.
	ServerID string `json:"server_id,omitempty"`

	// ConnType is the type of connection requested, either node or application.
	ConnType types.TunnelType `json:"conn_type"`
}

DialReq is a request for the address to connect to. Supports special non-resolvable addresses and search names if connection over a tunnel.

func (*DialReq) CheckAndSetDefaults

func (d *DialReq) CheckAndSetDefaults() error

CheckAndSetDefaults verifies all the values are valid.

type HandshakePayload

type HandshakePayload struct {
	// ClientAddr is the IP address of the remote client
	ClientAddr string `json:"clientAddr,omitempty"`
	// TracingContext contains tracing information so that spans can be correlated
	// across ssh boundaries
	TracingContext map[string]string `json:"tracingContext,omitempty"`
}

HandshakePayload structure is sent as a JSON blob by the teleport proxy to every SSH server who identifies itself as Teleport server

It allows teleport proxies to communicate additional data to server

type HostKeyCallbackConfig

type HostKeyCallbackConfig struct {
	// GetHostCheckers is used to fetch host checking (public) keys.
	GetHostCheckers CheckersGetter
	// HostKeyFallback sets optional callback to check non-certificate keys.
	HostKeyFallback ssh.HostKeyCallback
	// FIPS allows to set FIPS mode which will validate algorithms.
	FIPS bool
	// OnCheckCert is called on SSH certificate validation.
	OnCheckCert func(*ssh.Certificate)
	// Clock is used to set the Checker Time
	Clock clockwork.Clock
}

HostKeyCallbackConfig is the host key callback configuration.

func (*HostKeyCallbackConfig) Check

func (c *HostKeyCallbackConfig) Check() error

Check validates the config.