sshfp

README

SSHFP resolver for Golang

NOTE: Package is functional but not production ready! It requires at least Golang 1.12 with Go modules

The sshfp project is a Golang implementation of SSH fingerprints stored in SSHFP DNS records which can be used together with golang.org/x/crypto/ssh.Client using a custom HostKeyCallback with modular caching. Learn more about the DNS SSHFP record type on Wikipedia.

At least go 1.12 is required

This package is based on the awesome Golang DNS package from github.com/miekg/dns.

And implements at least the following RFCs:

• https://www.ietf.org/rfc/rfc1035.txt
• https://tools.ietf.org/rfc/rfc6594.txt
• https://www.ietf.org/rfc/rfc4255.txt
• https://tools.ietf.org/html/rfc7479

LICENSE

MIT

Documentation

Overview

Package sshfp implements a ssh.HostKeyCallback for resolving SSH host key fingerprints using DNS

Overview

The most basic resolver is created as follows (without error checking):

r := sshfp.NewResolver(sshfp.WithDNSClientConfigFromFile("/etc/resolv.conf"))

sshClientConfig := &ssh.ClientConfig{
    HostKeyCallback: r.HostKeyCallback,
}

c, err := ssh.Dial("tcp", "remote.example.org:22", sshClientConfig)
... Check error and do something with the SSHFP validated connected client

Index

• Constants
• Variables
• func ParseHostname(hostname string) (*url.URL, error)
• type Algorithm
  • func AlgorithmFromSSHPublicKey(pubKey ssh.PublicKey) Algorithm
  • func (a Algorithm) String() string
• type Cache
• type Entries
  • func ParseZone(r io.Reader) (Entries, error)
• type Entry
  • func (e *Entry) IsExpired() bool
  • func (e *Entry) IsValid() bool
  • func (e *Entry) String() string
  • func (e *Entry) TTL() uint32
  • func (e *Entry) Validate(pubKey ssh.PublicKey) bool
• type MemoryCache
  • func NewMemoryCache() (*MemoryCache, error)
  • func (mc *MemoryCache) Add(e ...*Entry) error
  • func (mc *MemoryCache) Get(hostname string, algo ...Algorithm) (Entries, bool)
  • func (mc *MemoryCache) Remove(e *Entry) error
• type Resolver
  • func NewResolver(opts ...ResolverOption) (*Resolver, error)
  • func (r *Resolver) HostKeyCallback(hostname string, remote net.Addr, key ssh.PublicKey) error
  • func (r *Resolver) LookupHost(hostname string) ([]*dns.SSHFP, error)
• type ResolverOption
  • func WithCache(c Cache) ResolverOption
  • func WithDNSClientConfigFromFile(resolvconf string) ResolverOption
  • func WithDNSClientConfigFromReader(resolvconf io.Reader) ResolverOption
• type Type
  • func (fp Type) String() string

Constants

const SSHURLScheme = "ssh"

SSHURLScheme is the URL scheme for SSH hostname urls

Variables

var ErrHostKeyChanged = fmt.Errorf("sshfp: host key changed")

ErrHostKeyChanged when the SSH server host key has changed

var ErrInvalidURLScheme = fmt.Errorf("sshfp: invalid url scheme")

ErrInvalidURLScheme when the hostname URL scheme is invalid

var ErrNoDNSServer = fmt.Errorf("sshfp: no dns server available")

ErrNoDNSServer when no DNS servers is available

var ErrNoHostKeyFound = fmt.Errorf("sshfp: no host key found")

ErrNoHostKeyFound when no host key is found in DNS (or cache)

Functions

func ParseHostname

func ParseHostname(hostname string) (*url.URL, error)

ParseHostname parses the hostname into a url.URL it automaticlly appends the SSHURLScheme

when not the hostname is not prefixed with a scheme. The URL scheme must be empty or
"ssh" else the function returns ErrInvalidURLScheme

Types

type Algorithm

type Algorithm uint8

Algorithm of the host public key

const (
	AlgorithmReserved Algorithm = 0
	AlgorithmRSA      Algorithm = 1
	AlgorithmDSS      Algorithm = 2
	AlgorithmECDSA    Algorithm = 3
	AlgorithmEd25519  Algorithm = 4
)

golint: nolint

func AlgorithmFromSSHPublicKey

func AlgorithmFromSSHPublicKey(pubKey ssh.PublicKey) Algorithm

AlgorithmFromSSHPublicKey calculates the Algorithm based on the ssh.PublicKey.Type() (ssh.KeyAlgo* string)

func (Algorithm) String

func (a Algorithm) String() string

String gets the algorithm string as defined in RFC. Reserved or unknown algorithms return "AlgorithmReserved"

type Cache

type Cache interface {
	Add(e ...*Entry) error
	Get(hostname string, algo ...Algorithm) (Entries, bool)
	Remove(e *Entry) error
}

Cache for DNS SSHFP entries

type Entries

type Entries []*Entry

Entries for a single Hostname

func ParseZone

func ParseZone(r io.Reader) (Entries, error)

ParseZone parses a RFC 1035 zonefile and creates a slice of Entry elements.

This is compatible with the entries the command `ssh-keygen -r <hostname>` generates.

type Entry

type Entry struct {
	*dns.SSHFP
	ExpiresAt   time.Time
	Hostname    string
	Fingerprint []byte
}

Entry wraps a DNS SSHFP entry used for caching

func (*Entry) IsExpired

func (e *Entry) IsExpired() bool

IsExpired checks if the entry is expired

func (*Entry) IsValid

func (e *Entry) IsValid() bool

IsValid checks if the entry is valid

func (*Entry) String

func (e *Entry) String() string

String creates a human readable presentation of the SSHFP entry <hostname> <algorithm string> <fingerprint type string>

func (*Entry) TTL

func (e *Entry) TTL() uint32

TTL calculates the remaining seconds the entry is valid. When ExpiresAt field is zero then it

never expires and returns math.MaxUint32.

func (*Entry) Validate

func (e *Entry) Validate(pubKey ssh.PublicKey) bool

Validate checks if the SSH public key is valid

type MemoryCache

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

MemoryCache is a in-memory cache

func NewMemoryCache

func NewMemoryCache() (*MemoryCache, error)

NewMemoryCache creates a new in-memory cache

func (*MemoryCache) Add

func (mc *MemoryCache) Add(e ...*Entry) error

Add entry to the cache

func (*MemoryCache) Get

func (mc *MemoryCache) Get(hostname string, algo ...Algorithm) (Entries, bool)

Get entries from the cache

func (*MemoryCache) Remove

func (mc *MemoryCache) Remove(e *Entry) error

Remove entry from the cache

type Resolver

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

Resolver resolves DNS SSHFP records

func NewResolver

func NewResolver(opts ...ResolverOption) (*Resolver, error)

NewResolver creates a new DNS SSHFP resolver

func (*Resolver) HostKeyCallback

func (r *Resolver) HostKeyCallback(hostname string, remote net.Addr, key ssh.PublicKey) error

HostKeyCallback with DNS SSHFP entry verification for golang.org/x/crypto/ssh

func (*Resolver) LookupHost

func (r *Resolver) LookupHost(hostname string) ([]*dns.SSHFP, error)

LookupHost looks up the given host for DNS SSHFP records

type ResolverOption

type ResolverOption func(*Resolver) error

ResolverOption for Resolver

func WithCache

func WithCache(c Cache) ResolverOption

WithCache sets a Cache for the Resolver

func WithDNSClientConfigFromFile

func WithDNSClientConfigFromFile(resolvconf string) ResolverOption

WithDNSClientConfigFromFile loads a resolv.conf(5) like file

func WithDNSClientConfigFromReader

func WithDNSClientConfigFromReader(resolvconf io.Reader) ResolverOption

WithDNSClientConfigFromReader works like WithDNSClientConfigFromFile but takes an io.Reader as argument

type Type

type Type uint8

Type of the fingerprint checksum

const (
	TypeReserved Type = 0
	TypeSHA1     Type = 1
	TypeSHA256   Type = 2
)

golint: nolint

func (Type) String

func (fp Type) String() string

String gets the fingerprint type string as defined in RFC. Reserved or unknown algorithms return "TypeReserved"