Documentation
¶
Overview ¶
Package sshhosts stores the SSH hosts SSHManager may connect to, the projects each host is associated with, and K-brain's own known_hosts file.
Hosts live in <dir>/hosts.json, host keys in <dir>/known_hosts (OpenSSH format); dir is created 0700 and both files are written 0600 through a staging file, the way config.json (which holds provider API keys) is. Secrets (password, private key, private key passphrase, proxy password) are stored as written and never leave the package except to open a connection: Public projects them to "...Configured" flags.
Index ¶
- Constants
- Variables
- func DeleteHost(doc *Document, id string) error
- func NormalizeAssociations(in map[string][]string, hosts []Host) map[string][]string
- func ParseProxyURL(raw, fallbackType string) (kind, authority string, err error)
- func ProjectPathKey(value string) string
- type Document
- type DocumentInput
- type Host
- type HostInput
- type HostKeyStatus
- type KnownHosts
- func (k *KnownHosts) Add(address string, key ssh.PublicKey) error
- func (k *KnownHosts) Algorithms(address string) []string
- func (k *KnownHosts) Check(address string, key ssh.PublicKey) (HostKeyStatus, []KnownKey, error)
- func (k *KnownHosts) Keys(address string) []KnownKey
- func (k *KnownHosts) Path() string
- func (k *KnownHosts) Public(h Host) PublicHost
- func (k *KnownHosts) Remove(address string) (int, error)
- type KnownKey
- type PortValue
- type Proxy
- type ProxyInput
- type PublicDocument
- type PublicHost
- type PublicProxy
- type Store
- func (s *Store) HasProjectHosts(project string) bool
- func (s *Store) Host(id string) (Host, bool)
- func (s *Store) KnownHosts() *KnownHosts
- func (s *Store) ProjectHosts(project string) []Host
- func (s *Store) Public() PublicDocument
- func (s *Store) Revision() uint64
- func (s *Store) Snapshot() Document
- func (s *Store) Update(base uint64, fn func(*Document) error) (Document, uint64, error)
Constants ¶
const ( AuthPassword = "password" AuthPrivateKey = "privateKey" AuthKeyboardInteractive = "keyboardInteractive" )
Auth types, as LiveAgent names them.
const ( CredentialSaved = "saved" CredentialMissing = "missing" CredentialInteractive = "interactive" )
Credential states list_hosts and GET /v1/settings/ssh report.
const ( MaxHosts = 256 MaxHostsPerProject = 64 )
Limits on what a client may store.
Variables ¶
var ErrConflict = errors.New("ssh settings changed; reload and retry")
ErrConflict is returned when an update names a base revision that is no longer current.
var ErrNotFound = errors.New("ssh host not found")
ErrNotFound is returned for an unknown host id.
var ErrSave = errors.New("save ssh hosts")
ErrSave is returned when the hosts file cannot be written.
Functions ¶
func DeleteHost ¶
DeleteHost removes the host id and its associations.
func NormalizeAssociations ¶
NormalizeAssociations keys associations by ProjectPathKey, drops ids of hosts not in hosts, duplicates and empty lists, and keeps at most MaxHostsPerProject ids per project. When two spellings of one project collide, the one already in canonical form wins (LiveAgent's rule).
func ParseProxyURL ¶
ParseProxyURL splits a proxy address ("host", "host:port" or "scheme://host[:port]") into its kind ("socks5" or "http") and authority. Credentials belong in the username and password fields, so an address with user info is refused.
func ProjectPathKey ¶
ProjectPathKey is the key a project's SSH host associations are stored under. It matches LiveAgent's project_path_key, so associations a client saves for a project path are found again from the run's working directory:
- Windows-like paths (drive letter, UNC, \\?\ prefix): the extended prefix is dropped, backslashes become slashes, trailing slashes above the root are trimmed and the result is lower-cased.
- Other paths: trailing slashes are trimmed (the root "/" stays).
Types ¶
type Document ¶
type Document struct {
Hosts []Host `json:"hosts"`
// ProjectHostAssociations maps a ProjectPathKey to the ids of the hosts
// SSHManager may use in that project.
ProjectHostAssociations map[string][]string `json:"projectHostAssociations"`
}
Document is the stored file.
type DocumentInput ¶
type DocumentInput struct {
BaseRevision uint64 `json:"baseRevision,omitempty"`
Hosts *[]HostInput `json:"hosts,omitempty"`
ProjectHostAssociations *map[string][]string `json:"projectHostAssociations,omitempty"`
Revision any `json:"revision,omitempty"`
KnownHostsPath any `json:"knownHostsPath,omitempty"`
}
DocumentInput is the body of PUT /v1/settings/ssh. A field that is absent keeps what is stored: Hosts, when present, is the complete host list (hosts left out are deleted, secrets of the others follow HostInput's rules); ProjectHostAssociations, when present, replaces every association. BaseRevision, when non-zero, must be the current revision. Revision and knownHostsPath from GET are accepted and ignored.
func (DocumentInput) ApplyTo ¶
func (in DocumentInput) ApplyTo(doc *Document) error
ApplyTo merges in into doc.
type Host ¶
type Host struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
Host string `json:"host"`
Port int `json:"port"`
Username string `json:"username,omitempty"`
AuthType string `json:"authType"`
Password string `json:"password,omitempty"`
PrivateKey string `json:"privateKey,omitempty"`
PrivateKeyPath string `json:"privateKeyPath,omitempty"`
PrivateKeyPassphrase string `json:"privateKeyPassphrase,omitempty"`
Proxy Proxy `json:"proxy"`
}
Host is one stored SSH host, secrets included. It never leaves the backend as is: Public is the projection clients see.
func Apply ¶
Apply merges in into stored (the zero Host when the id is new) and validates the result.
func (Host) ConnectionFingerprint ¶
ConnectionFingerprint is connectionFingerprint for other packages; it is an opaque value that includes secrets and must never be shown or logged.
func (Host) Credential ¶
Credential reports whether connecting needs nothing from the user (saved), is impossible until credentials are stored (missing), or needs the user to answer the server's prompts (interactive).
type HostInput ¶
type HostInput struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
Host string `json:"host"`
Port PortValue `json:"port,omitempty"`
Username string `json:"username,omitempty"`
AuthType string `json:"authType,omitempty"`
Password string `json:"password,omitempty"`
ClearPassword bool `json:"clearPassword,omitempty"`
PrivateKey string `json:"privateKey,omitempty"`
ClearPrivateKey bool `json:"clearPrivateKey,omitempty"`
PrivateKeyPath string `json:"privateKeyPath,omitempty"`
PrivateKeyPassphrase string `json:"privateKeyPassphrase,omitempty"`
ClearPrivateKeyPassphrase bool `json:"clearPrivateKeyPassphrase,omitempty"`
Proxy *ProxyInput `json:"proxy,omitempty"`
PasswordConfigured any `json:"passwordConfigured,omitempty"`
PrivateKeyConfigured any `json:"privateKeyConfigured,omitempty"`
PrivateKeyPassphraseConfigured any `json:"privateKeyPassphraseConfigured,omitempty"`
Credential any `json:"credential,omitempty"`
HostKeys any `json:"hostKeys,omitempty"`
}
HostInput is a host as a client sends it. Secret fields follow the provider API key rules: empty keeps the stored value, a value replaces it, and the matching clear flag removes it. The "...Configured", credential and hostKeys fields GET returns are accepted and ignored, so a client can send back what it read.
type HostKeyStatus ¶
type HostKeyStatus int
HostKeyStatus is how a presented host key compares with known_hosts.
const ( // HostKeyTrusted: known_hosts has this key for the host. HostKeyTrusted HostKeyStatus = iota // HostKeyUnknown: known_hosts has no key for the host. HostKeyUnknown // HostKeyChanged: known_hosts has other keys for the host, or the key is // revoked. HostKeyChanged )
type KnownHosts ¶
type KnownHosts struct {
// contains filtered or unexported fields
}
KnownHosts is K-brain's own known_hosts file (OpenSSH format). It is never the user's ~/.ssh/known_hosts: K-brain trusts only keys the user accepted through K-brain.
func NewKnownHosts ¶
func NewKnownHosts(path string) *KnownHosts
NewKnownHosts uses the file at path.
func (*KnownHosts) Add ¶
func (k *KnownHosts) Add(address string, key ssh.PublicKey) error
Add trusts key for address.
func (*KnownHosts) Algorithms ¶
func (k *KnownHosts) Algorithms(address string) []string
Algorithms lists the host key algorithms to offer for address so the server presents a key of a stored type; nil when none is stored.
func (*KnownHosts) Check ¶
func (k *KnownHosts) Check(address string, key ssh.PublicKey) (HostKeyStatus, []KnownKey, error)
Check compares key, presented by address (host:port), with the file. For HostKeyChanged, known lists the keys stored for the host.
func (*KnownHosts) Keys ¶
func (k *KnownHosts) Keys(address string) []KnownKey
Keys lists the keys stored for address.
func (*KnownHosts) Public ¶
func (k *KnownHosts) Public(h Host) PublicHost
Public projects h for clients.
type KnownKey ¶
type KnownKey struct {
Algorithm string `json:"algorithm"`
Fingerprint string `json:"fingerprint"`
}
KnownKey describes a stored host key without its bytes.
type PortValue ¶
type PortValue int
PortValue accepts a port as a JSON number, a numeric string, "" or null.
func (*PortValue) UnmarshalJSON ¶
type Proxy ¶
type Proxy struct {
// Type is "socks5" (default) or "http"; a scheme in URL wins.
Type string `json:"type"`
URL string `json:"url,omitempty"`
Port int `json:"port,omitempty"`
Username string `json:"username,omitempty"`
Password string `json:"password,omitempty"`
UseSystemProxy bool `json:"useSystemProxy,omitempty"`
}
Proxy is the optional proxy a host is reached through.
func (Proxy) Configured ¶
Configured reports whether a proxy is set up (LiveAgent's rule).
type ProxyInput ¶
type ProxyInput struct {
Type string `json:"type,omitempty"`
URL string `json:"url,omitempty"`
Port PortValue `json:"port,omitempty"`
Username string `json:"username,omitempty"`
Password string `json:"password,omitempty"`
ClearPassword bool `json:"clearPassword,omitempty"`
UseSystemProxy bool `json:"useSystemProxy,omitempty"`
PasswordConfigured any `json:"passwordConfigured,omitempty"`
}
ProxyInput is a host's proxy as a client sends it; Password follows the secret rules of HostInput.
type PublicDocument ¶
type PublicDocument struct {
Revision uint64 `json:"revision"`
Hosts []PublicHost `json:"hosts"`
ProjectHostAssociations map[string][]string `json:"projectHostAssociations"`
KnownHostsPath string `json:"knownHostsPath"`
}
PublicDocument is the body of GET /v1/settings/ssh.
type PublicHost ¶
type PublicHost struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description"`
Host string `json:"host"`
Port int `json:"port"`
Username string `json:"username"`
AuthType string `json:"authType"`
Password string `json:"password"`
PasswordConfigured bool `json:"passwordConfigured"`
PrivateKey string `json:"privateKey"`
PrivateKeyPath string `json:"privateKeyPath"`
PrivateKeyConfigured bool `json:"privateKeyConfigured"`
PrivateKeyPassphrase string `json:"privateKeyPassphrase"`
PrivateKeyPassphraseConfigured bool `json:"privateKeyPassphraseConfigured"`
Proxy PublicProxy `json:"proxy"`
Credential string `json:"credential"`
HostKeys []KnownKey `json:"hostKeys"`
}
PublicHost is a host as GET /v1/settings/ssh returns it: LiveAgent's SshHostConfig shape with every secret blanked and reported through its "...Configured" flag, plus credential and the stored host keys.
type PublicProxy ¶
type PublicProxy struct {
Type string `json:"type"`
URL string `json:"url"`
Port int `json:"port"`
Username string `json:"username"`
Password string `json:"password"`
PasswordConfigured bool `json:"passwordConfigured"`
UseSystemProxy bool `json:"useSystemProxy"`
}
PublicProxy is a host's proxy with its password blanked.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store holds the hosts document and its file.
func (*Store) HasProjectHosts ¶
HasProjectHosts reports whether project has any associated host.
func (*Store) KnownHosts ¶
func (s *Store) KnownHosts() *KnownHosts
KnownHosts is the store's known_hosts file.
func (*Store) ProjectHosts ¶
ProjectHosts returns the stored hosts associated with the project whose path (or key) is project, in association order.
func (*Store) Public ¶
func (s *Store) Public() PublicDocument
Public projects the whole store for clients.