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
- type Transport
- 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)
Constants ¶
This section is empty.
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 ¶
Types ¶
type Listener ¶
A Listener is a TCP network listener for TLS-secured connections.
func Listen ¶
Listen sets up a new server. If an error is returned, it means the server isn't ready to begin listening.
func (*Listener) AutoUpdate ¶
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 *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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ca provides the CertificateAuthority interface for the transport package, which provides an interface to get a CSR signed by some certificate authority.
|
Package ca provides the CertificateAuthority interface for the transport package, which provides an interface to get a CSR signed by some certificate authority. |
|
localca
Package localca implements a localca that is useful for testing the transport package.
|
Package localca implements a localca that is useful for testing the transport package. |
|
Package core contains core definitions for the transport package, the most salient of which is likely the Identity type.
|
Package core contains core definitions for the transport package, the most salient of which is likely the Identity type. |
|
example
|
|
|
exlib
Package exlib contains common library code for the examples.
|
Package exlib contains common library code for the examples. |
|
Package kp describes transport key providers and provides a reference implementation.
|
Package kp describes transport key providers and provides a reference implementation. |
|
Package roots includes support for loading trusted roots from various sources.
|
Package roots includes support for loading trusted roots from various sources. |