README
¶
tofu
Introduction
This package implements the TOFU (trust on first use) authentication scheme.
To read more about it, check out the following links:
Usage
tofu provides an interface, Store, to allow the library consumer to
choose how they want to manage their known hosts.
There are two implementations, a FileStore and an InMemoryStore.
When using FileStore, the implementation assumes a format similar to the
known_hosts file used by SSH, each line is a comma-separated set of values:
- hash(address)
- fingerprint - hash(data)
- comment (optional)
Example
Define a connection verification function.
var (
ErrInvalidCert = errors.New("invalid certificate")
ErrNoPeerCerts = errors.New("no peer certificates")
)
func verifyConn(store tofu.Store) verifyFunc {
return func(state tls.ConnectionState) error {
// check for peer certificates
peerCerts := state.PeerCertificates
if len(peerCerts) == 0 {
return ErrNoPeerCerts
}
leaf := state.PeerCertificates[0]
// get fingerprint
host := tofu.Host{
Address: state.ServerName,
Fingerprint: tofu.Fingerprint(leaf),
}
// verify host with fingerprint
valid, err := tofu.Verify(store, host)
if err != nil {
return fmt.Errorf("error verifying: %w", err)
}
if !valid {
return ErrInvalidCert
}
return nil
}
}
Pass it into a tls.Config
const minTLSVersion = tls.VersionTLS12
config := &tls.Config{
MinVersion: minTLSVersion,
InsecureSkipVerify: true,
VerifyConnection: verifyConn(myCertStore),
}
Documentation
¶
Overview ¶
Package tofu implements the TOFU (trust on first use) authentication scheme.
To read more about it, check out the following links:
Usage ¶
The package provides an interface, Store, to allow the library consumer to choose however they want to handle known hosts.
There are two implementations, FileStore and InMemoryStore.
When using FileStore, the implementation assumes a format similar to the known_hosts file used by SSH, that is, each line is a comma-separated set of values:
- hash(address)
- fingerprint - hash(data)
- comment (optional)
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrHostAlreadyExists = errors.New("host already exists") ErrHostNotFound = errors.New("host not found") )
Functions ¶
func Fingerprint ¶
func Fingerprint(cert *x509.Certificate) string
Fingerprint returns the md5 hash of the DER encoded bytes.
Types ¶
type FileStore ¶
type FileStore struct {
// contains filtered or unexported fields
}
FileStore is implemented as an InMemoryStore that is backed by a file. By convention, the public methods can be assumed to be concurrency-safe but none of the private methods should be assumed to be concurrency-safe as they may not be.
@TODO: the mutex should be used and named better (fileMutex?).
func NewFileStore ¶
func (*FileStore) Add ¶
Add will add a Host to the list of known hosts. If the host has already been added, it will return a ErrHostAlreadyExists error instead.
type InMemoryStore ¶
type InMemoryStore struct {
// contains filtered or unexported fields
}
InMemoryStore is a concurrency-safe in-memory store of known hosts.
func NewInMemoryStore ¶
func NewInMemoryStore() *InMemoryStore
func (*InMemoryStore) Add ¶
func (store *InMemoryStore) Add(host Host) error
Add will add a Host to the list of known hosts. If the Host has already been added, it will return a ErrHostAlreadyExists error instead.
func (*InMemoryStore) Delete ¶
func (store *InMemoryStore) Delete(address string) error
Delete will delete the Host matching address. If it has not been added, ErrHostNotFound will be returned.
type Store ¶
type Store interface {
// Add will add a host. If it is already known, it is
// expected implementations will return ErrHostAlreadyExists.
Add(h Host) error
// Delete will delete the host if it is found, otherwise
// it is expected implementations will return ErrHostNotFound.
Delete(address string) error
// Lookup will check if a host is present otherwise it
// is expected that implementations will return ErrHostNotFound.
Lookup(address string) (Host, error)
}
Source Files