cfssl: github.com/cloudflare/cfssl/transport Index | Files | Directories

package transport

import "github.com/cloudflare/cfssl/transport"

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

Package Files

client.go doc.go listener.go

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.

func Dial Uses

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.

type Listener Uses

type Listener struct {
    *Transport
    net.Listener
}

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

func Listen Uses

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 Uses

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 Uses

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 *backoff.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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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.

Directories

PathSynopsis
caPackage ca provides the CertificateAuthority interface for the transport package, which provides an interface to get a CSR signed by some certificate authority.
ca/localcaPackage localca implements a localca that is useful for testing the transport package.
corePackage core contains core definitions for the transport package, the most salient of which is likely the Identity type.
example/exlibPackage exlib contains common library code for the examples.
example/maclient
example/maserver
kpPackage kp describes transport key providers and provides a reference implementation.
rootsPackage roots includes support for loading trusted roots from various sources.
roots/system

Package transport imports 13 packages (graph) and is imported by 23 packages. Updated 2019-07-30. Refresh now. Tools for package owners.