README
¶
sshhostkey
This library provides a builder to create a SSH host key verification function to set in your ssh.ClientConfig.
Host keys can be verified using your known_hosts file (in your home dir), arbitrary known_hosts files or entries, or SSHFP records.
SSHFP records are fetched over classic DNS, DoT (DNS over TLS) or DoH (DNS over HTTPS). They must be verified with DNSSEC and SHA-1 records are ignored for security reasons.
Example
Using your known_hosts file
var builder sshhostkey.Builder
if err != builder.WithMyKnownHostsFile(); err != nil {
panic(err)
}
verifFunc, err := builder.Build()
if err != nil {
panic(err)
}
sshConf := &ssh.Config{
HostKeyCallback: verifFunc,
}
Using SSHFP records
var builder sshhostkey.Builder
if err := builder.WithThisDNSResolver("https://ns0.fdn.fr", sshhostkey.DNSOverHTTPS); err != nil {
panic(err)
}
if err := builder.WithThisCACertificateFile("/etc/ssl/certs/ca-certificates.crt"); err != nil {
panic(err)
}
verifFunc, err := builder.Build()
if err != nil {
panic(err)
}
sshConf := &ssh.ClientConfig{
HostKeyCallback: verifFunc,
}
Documentation
¶
Overview ¶
Package sshhostkey provides a builder for a SSH HostKeyCallback function verifying the server key via known_hosts files or entries, and SSHFP records published in the DNS
Index ¶
- Variables
- type Builder
- func (cb Builder) Build() (ssh.HostKeyCallback, error)
- func (cb *Builder) WithMyKnownHostsFile() error
- func (cb *Builder) WithThisCACertificateFile(files ...string) error
- func (cb *Builder) WithThisCertificateAuthority(certBytes []byte) error
- func (cb *Builder) WithThisDNSResolver(addr string, protocol DNSProtocol) error
- func (cb *Builder) WithThisKnownHostEntry(entries ...string) error
- func (cb *Builder) WithThisKnownHostsFile(files ...string) error
- func (cb *Builder) WithThisReadLimit(limit uint)
- type DNSProtocol
Constants ¶
This section is empty.
Variables ¶
var ( // ErrHomeNotFound is returned when the HOME environment variable is not set and necessary to verify the host key ErrHomeNotFound = errors.New("failed to resolve HOME environment variable") // ErrTooManyEntries is returned when the specified file size exceeeds the read limit defined by calling Builder.WithThisReadLimit() ErrTooManyEntries = errors.New("file containing too many entries") // ErrMissingVerificationMechanism is returned if the Builder.Build function is called prior to the configuration of a verification mechanism ErrMissingVerificationMechanism = errors.New("no verification mechanism was specified. Please configure at least one of them") // ErrMissingCA is returned when a verification mechanism requiring a certificate verification is configured but no trusted certification authority was defined ErrMissingCA = errors.New("when using TLS (DoT or DoH), at least one certificate authority must be specified to verify the server certificate") // ErrKeyMismatch is returned when no verification mechanism were able to verify the key sent by the SSH server ErrKeyMismatch = errors.New("the key provided by the SSH server does not match the expected key") // ErrHostNotFound is returned when a key verification over DNS failed to resolve the domain name used to identify the SSH server ErrHostNotFound = errors.New("the hostname specified during the Dial call does not match the hostnames specified in the known host entry") // ErrRecordNotFound is returned when a key verification over DNS failed to find a SSHFP record at the domain name used to identify the SSH server ErrRecordNotFound = errors.New("SSHFP DNS record not found at the domain name specified in the Dial call") // ErrNoDNSSEC is returned when a key verification over DNS failed because the received DNS answer was missing the Authenticated Data bit indicating that the response was signed and verified with DNSSEC ErrNoDNSSEC = errors.New("missing AD bit on DNS response. Only DNSSEC verified responses are considered") // ErrNoMatchingRecord is returned when a key verification over DNS failed because SSHFP records were found but none was secure enough or relevant (different algorithm...) ErrNoMatchingRecord = errors.New("no SSHFP records matched the received public key") // ErrInvalidHostname is returned when the hostname of the SSH server does not match our regular expression and we could not extract the required info to proceed ErrInvalidHostname = errors.New("hostname/address does not match the expected regular expression") )
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder is the type of the HostKeyCallback callback builder. That is the "main" type provided by this package.
func (Builder) Build ¶
func (cb Builder) Build() (ssh.HostKeyCallback, error)
Build returns a HostKeyCallback function to set the HostKeyCallback of your ssh.ClientConfig configuration
func (*Builder) WithMyKnownHostsFile ¶
WithMyKnownHostsFile specifies that the $HOME/.ssh/known_hosts file content can be used to validate the SSH server host keys
func (*Builder) WithThisCACertificateFile ¶
WithThisCACertificateFile can be used to specify certificate authorities to use to verify the certificates used by DoT or DoH servers. Each file may contain one or multiple X.509 certificates encoded as PEM.
func (*Builder) WithThisCertificateAuthority ¶
WithThisCertificateAuthority can be used to specify a X.509 certificate to use to verify DoT and DoH certificates. The provided certificate must be encoded in DER format.
func (*Builder) WithThisDNSResolver ¶
func (cb *Builder) WithThisDNSResolver(addr string, protocol DNSProtocol) error
WithThisDNSResolver configures the builder to use the DNS to fetch SSHFP records validating the SSH host key. addr is a string representing the host and port to send packets to or to connect to. Example: "127.0.0.53:53" protocol specifies the protocol (classic DNS, DoT or DoH) to use to connect to the specified address. Answers returned by the DNS server must have the AD bit set. A retry over TCP is performed if the UDP response is truncated.
func (*Builder) WithThisKnownHostEntry ¶
WithThisKnownHostEntry configures the builder to use the specified strings as lines of a "virtual" known_hosts file
func (*Builder) WithThisKnownHostsFile ¶
WithThisKnownHostsFile configures the builder to use the specified files as known_hosts files not stored in the HOME dir
func (*Builder) WithThisReadLimit ¶
WithThisReadLimit specifies the maximum number of bytes that will be read from a file ($HOME/.ssh/known_hosts, files specified with WithThisKnownHostsFile and files specified with WithThisCACertificateFile). 0 means unlimited
type DNSProtocol ¶
type DNSProtocol int
DNSProtocol specifies which protocols may be used to query a DNS resolver
const ( // DNSOverUDPOrTCP specifies that the DNS resolver may be queried over UDP or TCP DNSOverUDPOrTCP DNSProtocol = iota // DNSOverTLS specifies that the DNS resolver may be queries with DoT. A certificate authority must be added to verify the DNS server certificate DNSOverTLS // DNSOverHTTPS specifies that the DNS resolver may be queries with DoH. A certificate authority must be added to verify the DNS server certificate DNSOverHTTPS )
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
tests
|
|
|
helpers/listener
Package listener provides helpers to easily create UDP/TCP connections
|
Package listener provides helpers to easily create UDP/TCP connections |