discovery

Documentation

Index

• Constants
• Variables
• func Run(options *Options) error
• type Certificate
• type CertificateChain
• type Connection
  • func (c Connection) GetCertificateChain(ctx context.Context, options *Options) (CertificateChain, error)
  • func (c Connection) String() string
• type DiscoveredChain
• type DiscoveredChainFunc
• type Options
  • func (o *Options) Clone() *Options
  • func (o Options) GetConnections() ([]*Connection, error)
  • func (o Options) Validate() error

Constants

const (
	ProtocolTLS = "tls"
	ProtocolSSH = "ssh"
)

Variables

var (
	// Debug enables debugging by directing this logger somewhere else
	Debug = log.New(ioutil.Discard, "", log.LstdFlags)
)

Functions

func Run

func Run(options *Options) error

Run goes and finds certificates

Types

type Certificate

type Certificate struct {
	// Protocol is either "ssh" or "tls" (one of the ProtocolXXXX strings)
	Protocol string

	// Description is a human-readable description of the certificate useful for display purposes
	Description string

	// KeyType is the encryption algorithm used for the public key
	KeyType string

	// SignatureType is the encryption algorithm used to sign the certificate
	SignatureType string

	// StartDate is the UTC date/time when the certificate can first be used
	StartDate time.Time

	// ExpiryDate is the UTC date/time when the certificate expires
	ExpiryDate time.Time

	// Raw is the raw certificate data (exact format depends on the protocol)
	Raw []byte
}

Certificate is an abstraction of some of the fields common to X.509 and SSH certificates.

type CertificateChain

type CertificateChain []*Certificate

CertificateChain is a chain of certificates obtained from a specific connection, with the end-entity certificate first.

type Connection

type Connection struct {
	IP   net.IP
	Port uint16

	// Protocol is one of the ProtocolXXXX strings, e.g. "ssh" or "tls". It indicates
	// how the connection will be made when checking for certificates.
	Protocol string

	// Host contains the original string which we resolved into IPs. It's useful for
	// TLS connections as we can set Server Name Indication in the ClientHello so that
	// multi-hosting TLS servers can present us with the correct certificate.
	Host string
}

Connection represents a connection that needs to be made to a specific IP address, port number and protocol combination to check for a certificate. It's really the specification for a connection which will be made.

func (Connection) GetCertificateChain

func (c Connection) GetCertificateChain(ctx context.Context, options *Options) (CertificateChain, error)

GetCertificateChain opens a connection to the IP address and port specified in the Connection and attempts a handshake using the Connection Protocol. It then returns the certificate chain it obtained, if any.

func (Connection) String

func (c Connection) String() string

String returns a string representation of the connection.

type DiscoveredChain

type DiscoveredChain struct {
	Connection *Connection
	Options    *Options

	// Chain may be empty if no certificate chain was found, or if an error occurred.
	Chain CertificateChain

	// Error may contain details of any error that occurred during discovery. If Error
	// is set then Chain will be nil.
	Error error
}

DiscoveredChain contains all of the data passed to the DiscoveredChainFunc callback.

type DiscoveredChainFunc

type DiscoveredChainFunc func(*DiscoveredChain)

DiscoveredChainFunc is a type which defines the action to take for each certificate chain found.

type Options

type Options struct {
	// Places is a list of strings specifying where to handshake with to
	// find certificates. Each place can be one of the following:
	// - An IP address, e.g. "172.16.1.2" (in which case the TCP port 443 is assumed)
	// - An IP address and port number, e.g. "172.16.1.2:8443"
	// - A URL with a scheme such as "https://" or "ssh://" and an IP host, e.g. "https://172.16.1.2" or "ssh://172.16.1.2"
	//
	// Note that a URL with a DNS name is not currently supported, but will be added
	// later.
	//
	// In future versions it is planned to support additional discovery mechanisms
	// such as Kubernetes service discovery using URL schemes and local filesystem
	// discovery.
	Places []string

	// ConfigSSH allows SSH client options to be supplied for any SSH places.
	ConfigSSH *ssh.ClientConfig

	// ConfigTLS allows TLS client options to be supplied for any TLS places.
	ConfigTLS *tls.Config

	// MaximumParallelConnections specifies the maximum number of connections which
	// will be attempted in parallel.
	MaximumParallelConnections int

	// Timeout specifies the maximum time to wait for a single connection attempt.
	// Useful for high network latency or unresponsive remote servers.
	Timeout time.Duration

	// DiscoveredChainFuncs is a slice of callback functions, each of which will be
	// called for each certificate chain found.
	DiscoveredChainFuncs []DiscoveredChainFunc
}

Options specifies where and how to find certificates.

func (*Options) Clone

func (o *Options) Clone() *Options

Clone makes a copy of an Options structure

func (Options) GetConnections

func (o Options) GetConnections() ([]*Connection, error)

GetConnections converts the list of Places into specific IP, port and protocol information.

func (Options) Validate

func (o Options) Validate() error

Validate checks that the Options are understood.