sshutil

README

sshutil

A Go helper library that provides additional SSH functionality and helper code for working with 'github.com/pkg/sftp' and 'golang.org/x/crypto/ssh'.

Documentation

Overview

Package sshutil provides additional SSH functionality and helper code for working with 'github.com/pkg/sftp' and 'golang.org/x/crypto/ssh'.

Index

• Constants
• func AddHostKeyToKnownHosts(knownHostsFilePath string, hostname string, key ssh.PublicKey) error
• func AllowAndAddHostKeyCallBack(hostname string, remote net.Addr, currentKey ssh.PublicKey) error
• func CurrentUserOpenSSHPrivateKeys() ([]ssh.Signer, error)
• func CurrentUserUnencryptedOpenSSHPrivateKeys() ([]ssh.Signer, error)
• func FindSSHPrivateKeys(config FindSSHPrivateKeysConfig) ([]ssh.Signer, error)
• func GetKnownHostsFile() (exists bool, filePath string, err error)
• func ImitateSSHClientHostKeyCallBack(promptFunc func(SSHHostKeyPromptInfo) bool) ssh.HostKeyCallback
• func IsPathSSHPrivateKey(pemFilePath string, label string) (ssh.Signer, bool, error)
• func IsSSHHostKnown(hostPublicKey ssh.PublicKey, hostname string, fileContents []byte) (bool, error)
• func OnlyAllowKnownHostsKeyCallBack(hostname string, remote net.Addr, currentKey ssh.PublicKey) error
• func UploadFileUsingScp(localFilePath string, destinationFilePath string, sshClient *ssh.Client, ...) error
• func UploadFileUsingSftp(localFilePath string, destinationFilePath string, sshClient *ssh.Client, ...) error
• type CommandOptions
• type CommandResult
  • func ExecuteCommand(command string, sshClient *ssh.Client, options CommandOptions) CommandResult
  • func (o CommandResult) FirstString(delimiter string) string
  • func (o CommandResult) IsError() bool
  • func (o CommandResult) IsOutputEmpty() bool
  • func (o CommandResult) LastString(delimiter string) string
• type FindSSHPrivateKeysConfig
  • func (o FindSSHPrivateKeysConfig) Validate() error
• type IsSSHPrivateKeyError
  • func (o IsSSHPrivateKeyError) Error() string
• type SSHHostKeyPromptInfo
• type TransferProgress
• type UploadOptions

Constants

const (
	ErrorCommandDidNotProduceOutput = "the executed command did not produce any output"
	ErrorNoKnownHostsFilePresent    = "the known hosts file does not exist"
	ErrorUnknownHostKey             = "the specified host is not present in the known hosts file"
	ErrorUploadTimeoutReached       = "upload timeout was exceeded"
	ErrorUploadCanceled             = "the upload was canceled"
)

const (
	DefaultKnownHostsFileMode = 0600
)

const (
	OpenSSHPrivateKeyPEMLabel = "OPENSSH PRIVATE KEY"
)

Functions

func AddHostKeyToKnownHosts

func AddHostKeyToKnownHosts(knownHostsFilePath string, hostname string, key ssh.PublicKey) error

AddHostKeyToKnownHosts adds a host key to the known hosts file.

func AllowAndAddHostKeyCallBack

func AllowAndAddHostKeyCallBack(hostname string, remote net.Addr, currentKey ssh.PublicKey) error

AllowAndAddHostKeyCallBack permits any host and adds its public key to the known hosts file.

func CurrentUserOpenSSHPrivateKeys

func CurrentUserOpenSSHPrivateKeys() ([]ssh.Signer, error)

CurrentUserOpenSSHPrivateKeys returns the current user's OpenSSH private keys. This function implements the input for the ssh.PublicKeysCallback wrapper function. The function itself wraps the FindSSHPrivateKeys function using the default configuration values.

Refer to FindSSHPrivateKeys for more information.

func CurrentUserUnencryptedOpenSSHPrivateKeys

func CurrentUserUnencryptedOpenSSHPrivateKeys() ([]ssh.Signer, error)

CurrentUserUnencryptedOpenSSHPrivateKeys returns only the current user's unencrypted OpenSSH private keys. This function implements the input for the ssh.PublicKeysCallback wrapper function.

Refer to FindSSHPrivateKeys for more information.

func FindSSHPrivateKeys

func FindSSHPrivateKeys(config FindSSHPrivateKeysConfig) ([]ssh.Signer, error)

FindSSHPrivateKeys searches for OpenSSH private keys, parses them, and returns the corresponding ssh.Signers using the specified config.

By default the function returns a non-nil error and a zero slice of ssh.Signer if any of the keys cannot be properly parsed.

func GetKnownHostsFile

func GetKnownHostsFile() (exists bool, filePath string, err error)

GetKnownHostsFile gets the path to the SSH known hosts file. The file path is not returned if the path could not be constructed. An error is returned when the file's path cannot be determined or if the file's mask is not equal to DefaultKnownHostsFileMode.

func ImitateSSHClientHostKeyCallBack

func ImitateSSHClientHostKeyCallBack(promptFunc func(SSHHostKeyPromptInfo) bool) ssh.HostKeyCallback

ImitateSSHClientHostKeyCallBack returns a ssh.HostKeyCallback that imitates the standard SSH command line client's behavior of prompting the user to verify an unknown public key, as well as rejecting mismatched public keys. This callback will call the provided promptFunc, which provides data about the host. The function should return 'true' if the user accepts the SSH host key. The function should return 'false' if the user does not accept the key.

func IsPathSSHPrivateKey

func IsPathSSHPrivateKey(pemFilePath string, label string) (ssh.Signer, bool, error)

IsPathSSHPrivateKey returns a non-nil ssh.Signer, true, and a nil error if the PEM file specified at pemFilePath with the specified PEM label is an SSH private key.

A PEM label is the portion of the PEM header that contains the expected data type. For example, the PEM label of the header:

-----BEGIN OPENSSH PRIVATE KEY-----

... would be:

OPENSSH PRIVATE KEY

Refer to RFC 7468 for more information: https://tools.ietf.org/html/rfc7468

If the file is not an SSH private key, nil ssh.Signer, false, and a nil error are returned. If the file is an SSH private key, but could not be parsed, then nil ssh.Signer, false, and a non-nil error of type *IsSSHPrivateKeyError is returned.

func IsSSHHostKnown

func IsSSHHostKnown(hostPublicKey ssh.PublicKey, hostname string, fileContents []byte) (bool, error)

IsSSHHostKnown determines if an SSH server is known by the client according to the known hosts file.

func OnlyAllowKnownHostsKeyCallBack

func OnlyAllowKnownHostsKeyCallBack(hostname string, remote net.Addr, currentKey ssh.PublicKey) error

OnlyKnownHostKeyCallBack only permits known hosts when connecting to a SSH server. ErrorUnknownHostKey is returned if the host key does not exist in the known hosts file.

func UploadFileUsingScp

func UploadFileUsingScp(localFilePath string, destinationFilePath string, sshClient *ssh.Client, options UploadOptions) error

UploadFileUsingScp uploads a file using SCP (Secure Copy Protocol). The resulting file name is determined by the value of the destination file path. I.e., specifying a destination of '/root/my-cool-file.txt' results in the file being named 'my-cool-file.txt' located in '/root'. Be aware that the '~' character is not supported. If a timeout occurs, then ErrorUploadTimeoutReached is returned.

func UploadFileUsingSftp

func UploadFileUsingSftp(localFilePath string, destinationFilePath string, sshClient *ssh.Client, options UploadOptions) error

UploadFileUsingSftp uploads a file using SFTP (SSH File Transfer Protocol). The resulting file name is determined by the value of the destination file path. I.e., specifying a destination of '/root/my-cool-file.txt' results in the file being named 'my-cool-file.txt' located in '/root'. Be aware that the '~' character is not supported. If a timeout occurs, then ErrorUploadTimeoutReached is returned.

Types

type CommandOptions

type CommandOptions struct {
	RequireOutput bool
	StripNewLine  bool
}

type CommandResult

type CommandResult struct {
	Output string
	Error  string
}

func ExecuteCommand

func ExecuteCommand(command string, sshClient *ssh.Client, options CommandOptions) CommandResult

ExecuteCommand executes a command on a remote machine using SSH.

func (CommandResult) FirstString

func (o CommandResult) FirstString(delimiter string) string

func (CommandResult) IsError

func (o CommandResult) IsError() bool

func (CommandResult) IsOutputEmpty

func (o CommandResult) IsOutputEmpty() bool

func (CommandResult) LastString

func (o CommandResult) LastString(delimiter string) string

type FindSSHPrivateKeysConfig

type FindSSHPrivateKeysConfig struct {
	DirPathFn    func() (string, error)
	IgnoreKeyErr func(error) bool
}

func (FindSSHPrivateKeysConfig) Validate

func (o FindSSHPrivateKeysConfig) Validate() error

type IsSSHPrivateKeyError

type IsSSHPrivateKeyError struct {
	FilePath              string
	UnableToOpen          bool
	StatFail              bool
	CurrentFileMode       os.FileMode
	BadFileMode           bool
	CopyContentsFail      bool
	ParseFail             bool
	RequiresPassphrase    bool
	OptionalUnderlyingErr error
	Message               string
}

func (IsSSHPrivateKeyError) Error

func (o IsSSHPrivateKeyError) Error() string

type SSHHostKeyPromptInfo

type SSHHostKeyPromptInfo struct {
	UserFacingPrompt    string
	FoundKnownHostsFile bool
	RemoteHostname      string
	RemotePublicKey     ssh.PublicKey
}

type TransferProgress

type TransferProgress struct {
	LocalFileSize  int64
	RemoteFileSize int64
	Percent        int
}

type UploadOptions

type UploadOptions struct {
	Cancel   chan bool
	Progress chan TransferProgress
	Timeout  time.Duration
}