leafcert

Documentation

Index

• Constants
• type CertSigner
  • func NewNetRPCCertSigner(netRPC NetRPC) CertSigner
• type Config
• type ConnectCALeafRequest
  • func (r *ConnectCALeafRequest) CacheInfo() cache.RequestInfo
  • func (r *ConnectCALeafRequest) Key() string
  • func (req *ConnectCALeafRequest) TargetNamespace() string
  • func (req *ConnectCALeafRequest) TargetPartition() string
• type Deps
• type Manager
  • func NewManager(deps Deps) *Manager
  • func (m *Manager) Get(ctx context.Context, req *ConnectCALeafRequest) (*structs.IssuedCert, cache.ResultMeta, error)
  • func (m *Manager) Notify(ctx context.Context, req *ConnectCALeafRequest, correlationID string, ...) error
  • func (m *Manager) NotifyCallback(ctx context.Context, req *ConnectCALeafRequest, correlationID string, ...) error
  • func (m *Manager) Prepopulate(ctx context.Context, key string, index uint64, value *structs.IssuedCert, ...) error
  • func (m *Manager) Stop()
• type NetRPC
• type RootsReader
  • func NewCachedRootsReader(cache *cache.Cache, dc string) RootsReader

Constants

const (
	DefaultLastGetTTL = 72 * time.Hour // reasonable default is days

	// DefaultLeafCertRefreshRate is the default rate at which certs can be refreshed.
	// This defaults to not being limited
	DefaultLeafCertRefreshRate = rate.Inf

	// DefaultLeafCertRefreshMaxBurst is the number of cache entry fetches that can
	// occur in a burst.
	DefaultLeafCertRefreshMaxBurst = 2

	DefaultLeafCertRefreshBackoffMin = 3               // 3 attempts before backing off
	DefaultLeafCertRefreshMaxWait    = 1 * time.Minute // maximum backoff wait time

	DefaultQueryTimeout = 10 * time.Minute
)

Types

type CertSigner

type CertSigner interface {
	SignCert(ctx context.Context, args *structs.CASignRequest) (*structs.IssuedCert, error)
}

func NewNetRPCCertSigner

func NewNetRPCCertSigner(netRPC NetRPC) CertSigner

NewNetRPCCertSigner returns a CertSigner that uses net-rpc to sign certs.

type Config

type Config struct {
	// LastGetTTL is the time that the certs returned by this type remain in
	// the cache after the last get operation. If a cert isn't accessed within
	// this duration, the certs is purged and background refreshing will cease.
	LastGetTTL time.Duration

	// LeafCertRefreshMaxBurst max burst size of RateLimit for a single cache entry
	LeafCertRefreshMaxBurst int

	// LeafCertRefreshRate represents the max calls/sec for a single cache entry
	LeafCertRefreshRate rate.Limit

	// LeafCertRefreshBackoffMin is the number of attempts to wait before
	// backing off.
	//
	// Mostly configurable just for testing.
	LeafCertRefreshBackoffMin uint

	// LeafCertRefreshMaxWait is the maximum backoff wait time.
	//
	// Mostly configurable just for testing.
	LeafCertRefreshMaxWait time.Duration

	// TestOverrideCAChangeInitialDelay allows overriding the random jitter
	// after a root change with a fixed delay. So far ths is only done in
	// tests. If it's zero the caChangeInitialSpreadDefault maximum jitter will
	// be used but if set, it overrides and provides a fixed delay. To
	// essentially disable the delay in tests they can set it to 1 nanosecond.
	// We may separately allow configuring the jitter limit by users later but
	// this is different and for tests only since we need to set a
	// deterministic time delay in order to test the behavior here fully and
	// determinstically.
	TestOverrideCAChangeInitialDelay time.Duration
}

type ConnectCALeafRequest

type ConnectCALeafRequest struct {
	Token         string
	Datacenter    string
	DNSSAN        []string
	IPSAN         []net.IP
	MinQueryIndex uint64
	MaxQueryTime  time.Duration
	acl.EnterpriseMeta
	MustRevalidate bool

	// The following flags indicate the entity we are requesting a cert for.
	// Only one of these must be specified.
	Service string              // Given a Service name, not ID, the request is for a SpiffeIDService.
	Agent   string              // Given an Agent name, not ID, the request is for a SpiffeIDAgent.
	Kind    structs.ServiceKind // Given "mesh-gateway", the request is for a SpiffeIDMeshGateway. No other kinds supported.
	Server  bool                // If true, the request is for a SpiffeIDServer.
}

ConnectCALeafRequest is the cache.Request implementation for the ConnectCALeaf cache type. This is implemented here and not in structs since this is only used for cache-related requests and not forwarded directly to any Consul servers.

func (*ConnectCALeafRequest) CacheInfo

func (r *ConnectCALeafRequest) CacheInfo() cache.RequestInfo

func (*ConnectCALeafRequest) Key

func (r *ConnectCALeafRequest) Key() string

func (*ConnectCALeafRequest) TargetNamespace

func (req *ConnectCALeafRequest) TargetNamespace() string

func (*ConnectCALeafRequest) TargetPartition

func (req *ConnectCALeafRequest) TargetPartition() string

type Deps

type Deps struct {
	Config Config
	Logger hclog.Logger

	// RootsReader is an interface to access connect CA roots.
	RootsReader RootsReader

	// CertSigner is an interface to remotely sign certificates.
	CertSigner CertSigner
}

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

func NewManager

func NewManager(deps Deps) *Manager

func (*Manager) Get

func (m *Manager) Get(ctx context.Context, req *ConnectCALeafRequest) (*structs.IssuedCert, cache.ResultMeta, error)

Get returns the leaf cert for the request. If data satisfying the minimum index is present, it is returned immediately. Otherwise, this will block until the cert is refreshed or the request timeout is reached.

Multiple Get calls for the same logical request will block on a single network request.

The timeout specified by the request will be the timeout on the cache Get, and does not correspond to the timeout of any background data fetching. If the timeout is reached before data satisfying the minimum index is retrieved, the last known value (maybe nil) is returned. No error is returned on timeout. This matches the behavior of Consul blocking queries.

func (*Manager) Notify

func (m *Manager) Notify(
	ctx context.Context,
	req *ConnectCALeafRequest,
	correlationID string,
	ch chan<- cache.UpdateEvent,
) error

Notify registers a desire to be updated about changes to a cache result.

It is a helper that abstracts code from performing their own "blocking" query logic against a cache key to watch for changes and to maintain the key in cache actively. It will continue to perform blocking Get requests until the context is canceled.

The passed context must be canceled or timeout in order to free resources and stop maintaining the value in cache. Typically request-scoped resources do this but if a long-lived context like context.Background is used, then the caller must arrange for it to be canceled when the watch is no longer needed.

The passed chan may be buffered or unbuffered, if the caller doesn't consume fast enough it will block the notification loop. When the chan is later drained, watching resumes correctly. If the pause is longer than the cachetype's TTL, the result might be removed from the local cache. Even in this case though when the chan is drained again, the new Get will re-fetch the entry from servers and resume notification behavior transparently.

The chan is passed in to allow multiple cached results to be watched by a single consumer without juggling extra goroutines per watch. The correlationID is opaque and will be returned in all UpdateEvents generated by result of watching the specified request so the caller can set this to any value that allows them to disambiguate between events in the returned chan when sharing a chan between multiple cache entries. If the chan is closed, the notify loop will terminate.

func (*Manager) NotifyCallback

func (m *Manager) NotifyCallback(
	ctx context.Context,
	req *ConnectCALeafRequest,
	correlationID string,
	cb cache.Callback,
) error

NotifyCallback allows you to receive notifications about changes to a cache result in the same way as Notify, but accepts a callback function instead of a channel.

func (*Manager) Prepopulate

func (m *Manager) Prepopulate(
	ctx context.Context,
	key string,
	index uint64,
	value *structs.IssuedCert,
	authorityKeyID string,
) error

Prepopulate puts a cert in manually. This is useful when the correct initial value is known and the cache shouldn't refetch the same thing on startup. It is used to set AgentLeafCert when AutoEncrypt.TLS is turned on. The manager itself cannot fetch that the first time because it requires a special RPCType. Subsequent runs are fine though.

func (*Manager) Stop

func (m *Manager) Stop()

Stop stops any background work and frees all resources for the manager. Current fetch requests are allowed to continue to completion and callers may still access the current leaf cert values so coordination isn't needed with callers, however no background activity will continue. It's intended to close the manager at agent shutdown so no further requests should be made, however concurrent or in-flight ones won't break.

type NetRPC

type NetRPC interface {
	RPC(ctx context.Context, method string, args any, reply any) error
}

NetRPC is an interface that an NetRPC client must implement. This is a helper interface that is implemented by the agent delegate so that Type implementations can request NetRPC access.

type RootsReader

type RootsReader interface {
	Get() (*structs.IndexedCARoots, error)
	Notify(ctx context.Context, correlationID string, ch chan<- cache.UpdateEvent) error
}

func NewCachedRootsReader

func NewCachedRootsReader(cache *cache.Cache, dc string) RootsReader

NewCachedRootsReader returns a RootsReader that sources data from the agent cache.