transport

Documentation

Overview

Package transport implements functions for facilitating proper TLS-secured communications for clients and servers.

Clients should build an identity (of the core.identity) type, such as

var id = &core.Identity{
         Request: &csr.CertificateRequest{
                 CN: "localhost test certificate",
         },
         Profiles: map[string]map[string]string{
                 "paths": map[string]string{
                         "private_key": "client.key",
                         "certificate": "client.pem",
                 },
                 "cfssl": {
                         "label":     "",
                         "profile":   "client-ca",
                         "remote":    "ca.example.net",
                         "auth-type": "standard",
                         "auth-key":  "000102030405060708090a0b0c0d0e0f",
                 },
         },
}

The New function will return a transport built using the NewKeyProvider and NewCA functions. These functions may be changed by other packages to provide common key provider and CA configurations. Clients can then use RefreshKeys (or launch AutoUpdate in a goroutine) to ensure the certificate and key are loaded and correct. The Listen and Dial functions then provide the necessary connection support.

The AutoUpdate function will handle automatic certificate issuance. Servers and clients are not required to take any special action when the certificate is updated: the key and certificate are only used when establishing a connection, and therefore existing connections are not affected---there is no need to reset or restart any existing connections. Clients should run AutoUpdate if they plan on making multiple connections or will be reconnecting; for a one-off connection, it isn't necessary.

Index

• Variables
• func Dial(address string, tr *Transport) (*tls.Conn, error)
• type Listener
  • func Listen(address string, tr *Transport) (*Listener, error)
  • func (l *Listener) AutoUpdate(certUpdates chan<- time.Time, errChan chan<- error)
• type Transport
  • func New(before time.Duration, identity *core.Identity) (*Transport, error)
  • func (tr *Transport) AutoUpdate(certUpdates chan<- time.Time, errChan chan<- error)
  • func (tr *Transport) Lifespan() time.Duration
  • func (tr *Transport) RefreshKeys() (err error)
  • func (tr *Transport) TLSClientAuthClientConfig(host string) (*tls.Config, error)
  • func (tr *Transport) TLSClientAuthServerConfig() (*tls.Config, error)
  • func (tr *Transport) TLSServerConfig() (*tls.Config, error)

Variables

var (
	// NewKeyProvider is the function used to build key providers
	// from some identity.
	NewKeyProvider = func(id *core.Identity) (kp.KeyProvider, error) {
		return kp.NewStandardProvider(id)
	}

	// NewCA is used to load a configuration for a certificate
	// authority.
	NewCA = func(id *core.Identity) (ca.CertificateAuthority, error) {
		return ca.NewCFSSLProvider(id, nil)
	}
)

var PollInterval = 30 * time.Second

PollInterval is how often to check whether a new certificate has been found.

Functions

func Dial

func Dial(address string, tr *Transport) (*tls.Conn, error)

Dial initiates a TLS connection to an outbound server. It returns a TLS connection to the server.

Types

type Listener

type Listener struct {
	*Transport
	net.Listener
}

A Listener is a TCP network listener for TLS-secured connections.

func Listen

func Listen(address string, tr *Transport) (*Listener, error)

Listen sets up a new server. If an error is returned, it means the server isn't ready to begin listening.

func (*Listener) AutoUpdate

func (l *Listener) AutoUpdate(certUpdates chan<- time.Time, errChan chan<- error)

AutoUpdate will automatically update the listener. If a non-nil certUpdates chan is provided, it will receive timestamps for reissued certificates. If errChan is non-nil, any errors that occur in the updater will be passed along.

type Transport

type Transport struct {
	// Before defines how long before the certificate expires the
	// transport should start attempting to refresh the
	// certificate. For example, if this is 24h, then 24 hours
	// before the certificate expires the Transport will start
	// attempting to replace it.
	Before time.Duration

	// Provider contains a key management provider.
	Provider kp.KeyProvider

	// CA contains a mechanism for obtaining signed certificates.
	CA ca.CertificateAuthority

	// TrustStore contains the certificates trusted by this
	// transport.
	TrustStore *roots.TrustStore

	// ClientTrustStore contains the certificate authorities to
	// use in verifying client authentication certificates.
	ClientTrustStore *roots.TrustStore

	// Identity contains information about the entity that will be
	// used to construct certificates.
	Identity *core.Identity

	// Backoff is used to control the behaviour of a Transport
	// when it is attempting to automatically update a certificate
	// as part of AutoUpdate.
	Backoff *core.Backoff

	// RevokeSoftFail, if true, will cause a failure to check
	// revocation (such that the revocation status of a
	// certificate cannot be checked) to not be treated as an
	// error.
	RevokeSoftFail bool
}

A Transport is capable of providing transport-layer security using TLS.

func New

func New(before time.Duration, identity *core.Identity) (*Transport, error)

New builds a new transport from an identity and a before time. The before time tells the transport how long before the certificate expires to start attempting to update when auto-updating. If before is longer than the certificate's lifetime, every update check will trigger a new certificate to be generated.

func (*Transport) AutoUpdate

func (tr *Transport) AutoUpdate(certUpdates chan<- time.Time, errChan chan<- error)

AutoUpdate will automatically update the listener. If a non-nil certUpdates chan is provided, it will receive timestamps for reissued certificates. If errChan is non-nil, any errors that occur in the updater will be passed along.

func (*Transport) Lifespan

func (tr *Transport) Lifespan() time.Duration

Lifespan returns how much time is left before the transport's certificate expires, or 0 if the certificate is not present or expired.

func (*Transport) RefreshKeys

func (tr *Transport) RefreshKeys() (err error)

RefreshKeys will make sure the Transport has loaded keys and has a valid certificate. It will handle any persistence, check that the certificate is valid (i.e. that its expiry date is within the Before date), and handle certificate reissuance as needed.

func (*Transport) TLSClientAuthClientConfig

func (tr *Transport) TLSClientAuthClientConfig(host string) (*tls.Config, error)

TLSClientAuthClientConfig returns a new client authentication TLS configuration that can be used for a client using client auth connecting to the named host.

func (*Transport) TLSClientAuthServerConfig

func (tr *Transport) TLSClientAuthServerConfig() (*tls.Config, error)

TLSClientAuthServerConfig returns a new client authentication TLS configuration for servers expecting mutually authenticated clients. The clientAuth parameter should contain the root pool used to authenticate clients.

func (*Transport) TLSServerConfig

func (tr *Transport) TLSServerConfig() (*tls.Config, error)

TLSServerConfig is a general server configuration that should be used for non-client authentication purposes, such as HTTPS.