sshx

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package sshx establishes SFTP sessions: it resolves hosts from OpenSSH config, authenticates with the agent, keys, or passwords, and verifies host keys against known_hosts.

Index

Constants

View Source
const DefaultPort = 22

DefaultPort is the standard SSH port.

Variables

View Source
var ErrAuthFailed = errors.New("authentication failed")

ErrAuthFailed means every authentication method was rejected.

View Source
var ErrCancelled = errors.New("cancelled")

ErrCancelled is returned by a Prompter when the user dismisses a prompt.

View Source
var ErrHostKeyRejected = errors.New("host key not trusted")

ErrHostKeyRejected means the user declined to trust an unknown host.

Functions

func DefaultSSHConfigPath

func DefaultSSHConfigPath() string

DefaultSSHConfigPath is ~/.ssh/config.

Types

type Conn

type Conn struct {
	Target Target
	SSH    *ssh.Client
	SFTP   *sftp.Client
}

Conn is an authenticated SSH connection with an SFTP session on top.

func Connect

func Connect(ctx context.Context, t Target, opts Options) (*Conn, error)

Connect dials t, verifies its host key, authenticates, and opens SFTP. Cancelling ctx aborts the attempt, including any prompt in progress.

func (*Conn) Close

func (c *Conn) Close() error

Close ends the SFTP session and the SSH connection.

func (*Conn) Wait

func (c *Conn) Wait() error

Wait blocks until the connection closes, returning why.

type Destination

type Destination struct {
	User string
	Host string
	Port int
	Path string
}

Destination is a parsed command-line destination such as "jsd@nas:/srv" or "sftp://jsd@nas:2222/srv". Zero values mean "not specified".

func ParseDestination

func ParseDestination(s string) (Destination, error)

ParseDestination parses [user@]host[:path] (scp style, IPv6 hosts in brackets) or sftp://[user@]host[:port][/path].

type HostKeyChangedError

type HostKeyChangedError struct {
	Host        string
	Fingerprint string
	File        string
}

HostKeyChangedError means the server presented a different key than the one in known_hosts. This is what a man-in-the-middle attack looks like, so it is never overridable from the UI.

func (*HostKeyChangedError) Error

func (e *HostKeyChangedError) Error() string

type HostKeyInfo

type HostKeyInfo struct {
	Alias       string
	Hostname    string // host[:port] as written to known_hosts
	Remote      net.Addr
	KeyType     string
	Fingerprint string // SHA256:...
	File        string // where the key will be saved
}

HostKeyInfo describes a host key the user is asked to trust.

type Options

type Options struct {
	// Prompter answers passphrase, password, and host key questions. Required.
	Prompter Prompter
	// Progress, if set, receives short status updates ("connecting", ...).
	Progress func(stage string)
}

Options tune Connect.

type Prompter

type Prompter interface {
	Ask(ctx context.Context, q Question) (string, error)
	ConfirmHostKey(ctx context.Context, info HostKeyInfo) (bool, error)
}

Prompter asks the user questions during a connection attempt. Methods are called from the connecting goroutine and may block until the user answers; they must return promptly when ctx is cancelled.

type Question

type Question struct {
	Title  string // short heading, e.g. "Password"
	Prompt string // e.g. "Password for jsd@nas"
	Secret bool   // hide what is typed
}

Question is a request for text from the user, e.g. a password.

type SSHConfig

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

SSHConfig is a parsed OpenSSH client config.

func EmptySSHConfig

func EmptySSHConfig() *SSHConfig

EmptySSHConfig is a config with no hosts, for when ~/.ssh/config can't be read.

func LoadSSHConfig

func LoadSSHConfig(path string) (*SSHConfig, error)

LoadSSHConfig reads an OpenSSH config file. A missing file yields an empty config.

func ParseSSHConfig

func ParseSSHConfig(b []byte, home string) (*SSHConfig, error)

ParseSSHConfig parses config text, expanding ~ against home.

func (*SSHConfig) Hosts

func (c *SSHConfig) Hosts() []string

Hosts lists the concrete (non-wildcard) host aliases in config order.

func (*SSHConfig) Resolve

func (c *SSHConfig) Resolve(alias string) Target

Resolve builds a Target for alias using the config, with OpenSSH defaults for anything unset.

func (*SSHConfig) TargetFor

func (c *SSHConfig) TargetFor(d Destination) Target

TargetFor resolves a destination: the host is looked up as an alias, and anything given explicitly (user, port, path) overrides the config.

type Target

type Target struct {
	// Alias is the name the user chose, e.g. "nas" from ~/.ssh/config.
	Alias string
	// Host is the address to dial (HostName in ssh config).
	Host string
	Port int
	User string
	// Path is an optional starting directory on the server.
	Path string

	IdentityFiles  []string
	IdentitiesOnly bool
	// KnownHostsFiles are checked for host keys; new keys are appended to
	// the first one.
	KnownHostsFiles []string
}

Target is everything needed to connect to one host.

func (Target) Addr

func (t Target) Addr() string

Addr is the host:port to dial.

func (Target) String

func (t Target) String() string

String renders the target as user@alias, plus the port when non-standard.

Directories

Path Synopsis
Package sshtest runs an in-process SSH server with an SFTP subsystem for tests, so connection and transfer code can be exercised without Docker or a real host.
Package sshtest runs an in-process SSH server with an SFTP subsystem for tests, so connection and transfer code can be exercised without Docker or a real host.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址