certprovider

Documentation

Overview

Package certprovider defines APIs for Certificate Providers in gRPC.

Experimental

Notice: All APIs in this package are experimental and may be removed in a later release.

Index

• func Register(b Builder)
• type Builder
• type Distributor
  • func NewDistributor() *Distributor
  • func (d *Distributor) KeyMaterial(ctx context.Context) (*KeyMaterial, error)
  • func (d *Distributor) Set(km *KeyMaterial, err error)
  • func (d *Distributor) Stop()
• type KeyMaterial
• type Options
• type Provider
  • func GetProvider(name string, config interface{}, opts Options) (Provider, error)
• type StableConfig

Functions

func Register

func Register(b Builder)

Register registers the Provider builder, whose name as returned by its Name() method will be used as the name registered with this builder. Registered Builders are used by the Store to create Providers.

Types

type Builder

type Builder interface {
	// Build creates a new Provider and initializes it with the given config and
	// options combination.
	Build(StableConfig, Options) Provider

	// ParseConfig converts config input in a format specific to individual
	// implementations and returns an implementation of the StableConfig
	// interface.
	// Equivalent configurations must return StableConfig types whose
	// Canonical() method returns the same output.
	ParseConfig(interface{}) (StableConfig, error)

	// Name returns the name of providers built by this builder.
	Name() string
}

Builder creates a Provider.

type Distributor

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

Distributor makes it easy for provider implementations to furnish new key materials by handling synchronization between the producer and consumers of the key material.

Provider implementations which choose to use a Distributor should do the following:

• create a new Distributor using the NewDistributor() function.
• invoke the Set() method whenever they have new key material or errors to report.
• delegate to the distributor when handing calls to KeyMaterial().
• invoke the Stop() method when they are done using the distributor.

func NewDistributor

func NewDistributor() *Distributor

NewDistributor returns a new Distributor.

func (*Distributor) KeyMaterial

func (d *Distributor) KeyMaterial(ctx context.Context) (*KeyMaterial, error)

KeyMaterial returns the most recent key material provided to the Distributor. If no key material was provided at the time of this call, it will block until the deadline on the context expires or fresh key material arrives.

func (*Distributor) Set

func (d *Distributor) Set(km *KeyMaterial, err error)

Set updates the key material in the distributor with km.

Provider implementations which use the distributor must not modify the contents of the KeyMaterial struct pointed to by km.

A non-nil err value indicates the error that the provider implementation ran into when trying to fetch key material, and makes it possible to surface the error to the user. A non-nil error value passed here causes distributor's KeyMaterial() method to return nil key material.

func (*Distributor) Stop

func (d *Distributor) Stop()

Stop turns down the distributor, releases allocated resources and fails any active KeyMaterial() call waiting for new key material.

type KeyMaterial

type KeyMaterial struct {
	// Certs contains a slice of cert/key pairs used to prove local identity.
	Certs []tls.Certificate
	// Roots contains the set of trusted roots to validate the peer's identity.
	Roots *x509.CertPool
}

KeyMaterial wraps the certificates and keys returned by a Provider instance.

type Options

type Options struct {
	// CertName holds the certificate name, whose key material is of interest to
	// the caller.
	CertName string
	// WantRoot indicates if the caller is interested in the root certificate.
	WantRoot bool
	// WantIdentity indicates if the caller is interested in the identity
	// certificate.
	WantIdentity bool
}

Options contains configuration knobs passed to a Provider at creation time.

type Provider

type Provider interface {
	// KeyMaterial returns the key material sourced by the Provider.
	// Callers are expected to use the returned value as read-only.
	KeyMaterial(ctx context.Context) (*KeyMaterial, error)

	// Close cleans up resources allocated by the Provider.
	Close()
}

Provider makes it possible to keep channel credential implementations up to date with secrets that they rely on to secure communications on the underlying channel.

Provider implementations are free to rely on local or remote sources to fetch the latest secrets, and free to share any state between different instantiations as they deem fit.

func GetProvider

func GetProvider(name string, config interface{}, opts Options) (Provider, error)

GetProvider returns a provider instance from which keyMaterial can be read.

name is the registered name of the provider, config is the provider-specific configuration, opts contains extra information that controls the keyMaterial returned by the provider.

Implementations of the Builder interface should clearly document the type of configuration accepted by them.

If a provider exists for passed arguments, its reference count is incremented before returning. If no provider exists for the passed arguments, a new one is created using the registered builder. If no registered builder is found, or the provider configuration is rejected by it, a non-nil error is returned.

type StableConfig

type StableConfig interface {
	// Canonical returns Provider config as an arbitrary byte slice.
	// Equivalent configurations must return the same output.
	Canonical() []byte
}

StableConfig wraps the method to return a stable Provider configuration.