hostkey

func AcceptUnknownHosts ¶ added in v2.2.0

func AcceptUnknownHosts(cb ssh.HostKeyCallback) ssh.HostKeyCallback

AcceptUnknownHosts wraps cb so that a host it has never seen is accepted rather than refused, while a host whose recorded key has changed remains a mismatch. Any other error is passed through untouched.

This is StrictHostKeyChecking=accept-new applied to a trust source that cannot be written to, such as a system-wide known_hosts file: the key is accepted but not recorded, so the next connection reaches the same decision again rather than pinning what it saw the first time. Where a writable user file exists, KnownHostsFileCallback is the better fit, since it records the key and so can detect a later change.

func KnownHostsFileCallback ¶

func KnownHostsFileCallback(path string, permissive, hash bool) (ssh.HostKeyCallback, error)

KnownHostsFileCallback returns a HostKeyCallback that uses a known hosts file to verify host keys.

func KnownHostsFileCallbackWithIPCheck ¶

func KnownHostsFileCallbackWithIPCheck(path string, permissive, hash bool) (ssh.HostKeyCallback, error)

KnownHostsFileCallbackWithIPCheck is like KnownHostsFileCallback but also verifies the connecting IP address, against the same file. The IP is checked first; see WithCheckHostIP for what that ordering is for.

func KnownHostsFilesCallback ¶ added in v2.2.0

func KnownHostsFilesCallback(writePath string, alsoVerify []string, permissive, hash bool) (ssh.HostKeyCallback, error)

KnownHostsFilesCallback verifies a host key against writePath and every file in alsoVerify, and records the key of a host that none of them knows in writePath.

That split is OpenSSH's: a new entry is appended to the first file, while every file counts when deciding whether the host is new at all. Verifying against writePath alone would classify a host as new whenever the first file happens not to mention it -- and then record and accept a key that a later user file, or a system-wide one, says belongs to a different host key.

Each alsoVerify path must be an existing regular file; writePath is created when it does not exist, since it is where a new key goes. That is a check on what the caller asked for: an alsoVerify file that goes missing later contributes nothing until it comes back, rather than failing every connection after it. writePath is held to more, before and after: it must be readable as well as writable, because a key it already holds is what tells a returning host from a new one, and a write-only file would make every host look new.

A writePath of /dev/null keeps no record, so a host that alsoVerify does not know is accepted without being stored -- but alsoVerify is still consulted, and a key it contradicts is still a mismatch. Only when alsoVerify is empty as well does that leave nothing to verify against, which is taken as the usual meaning of the null device: no host key verification.

func KnownHostsFilesCallbackWithIPCheck ¶ added in v2.2.0

func KnownHostsFilesCallbackWithIPCheck(writePath string, alsoVerify []string, permissive, hash bool) (ssh.HostKeyCallback, error)

KnownHostsFilesCallbackWithIPCheck is KnownHostsFilesCallback with the connecting IP address verified as well, against the same files. The IP is checked first; see WithCheckHostIP for what that ordering is for.

func KnownHostsReadOnlyFileCallback ¶

func KnownHostsReadOnlyFileCallback(path string, permissive bool) (ssh.HostKeyCallback, error)

KnownHostsReadOnlyFileCallback returns a HostKeyCallback that only reads from an existing known hosts file — it never creates the file or appends new entries. This is appropriate for system-wide files such as /etc/ssh/ssh_known_hosts that should not be modified by unprivileged users.

func KnownHostsReadOnlyFileCallbackWithIPCheck ¶

func KnownHostsReadOnlyFileCallbackWithIPCheck(path string, permissive bool) (ssh.HostKeyCallback, error)

KnownHostsReadOnlyFileCallbackWithIPCheck is like KnownHostsReadOnlyFileCallback but also verifies the connecting IP address, against the same file. The IP is checked first; see WithCheckHostIP for what that ordering is for.

func KnownHostsReadOnlyFilesCallback ¶ added in v2.2.0

func KnownHostsReadOnlyFilesCallback(paths []string, permissive bool) (ssh.HostKeyCallback, error)

KnownHostsReadOnlyFilesCallback is KnownHostsReadOnlyFileCallback over several known_hosts files read as one trust set: a key matching an entry in any of them is accepted, and a host is unknown only when none of them mentions it. That is how OpenSSH reads a user's file together with the system-wide ones, and it is what lets an administrator's entry in /etc/ssh/ssh_known_hosts count even when the user's own file has never heard of the host.

Every path must be an existing regular file. /dev/null is not special here: a caller combining trust sources has no use for one that verifies nothing, and it is not a regular file, so it is rejected like any other non-file.

func KnownHostsReadOnlyFilesCallbackWithIPCheck ¶ added in v2.2.0

func KnownHostsReadOnlyFilesCallbackWithIPCheck(paths []string, permissive bool) (ssh.HostKeyCallback, error)

KnownHostsReadOnlyFilesCallbackWithIPCheck is KnownHostsReadOnlyFilesCallback with the connecting IP address verified as well, against the same files. The IP is checked first; see WithCheckHostIP for what that ordering is for.

func StaticKeyCallback ¶

func StaticKeyCallback(trustedKey string) ssh.HostKeyCallback

StaticKeyCallback returns a HostKeyCallback that checks the host key against a given host key.

func WithAlias ¶

func WithAlias(callback ssh.HostKeyCallback, alias string) ssh.HostKeyCallback

WithAlias wraps callback so that alias replaces the actual hostname for all known_hosts lookups and new-entry storage. This implements the HostKeyAlias ssh_config option: connecting through a bastion or tunnel stores the entry under the logical alias, not the TCP address.

func WithCheckHostIP ¶

func WithCheckHostIP(callback ssh.HostKeyCallback, path string, permissive bool) (ssh.HostKeyCallback, error)

WithCheckHostIP wraps callback to also verify the connecting IP address in known_hosts. When the remote address is a TCP connection the actual connected IP is checked directly; otherwise all DNS-resolved addresses are checked. If the IP is found in known_hosts with a different key (potential DNS spoofing), ErrHostKeyMismatch is returned. DNS resolution failures are non-fatal. Skipped when hostname is already an IP address. Unlike OpenSSH, this implementation never writes IP addresses to known_hosts.

The IP is checked before callback runs, so a recording callback cannot store a key the file already contradicts under the connecting IP. The two checks read the files separately, each seeing them as they are when it runs, rather than sharing one read: they are not one atomic look at known_hosts, and an entry written between them belongs to whichever check follows it. That is the same race as an entry written just before the callback, and it is decided the same way -- by the next connection, which reads the file again.