workload

Documentation

Overview

Package workload provides a Workload API Client implementation. It allows a workload to get automatically rotated X.509 certificates from a Workload API Server. The watcher interface must be implemented to get notifications about SVIDs rotation and errors.

A full example is available at: https://github.com/spiffe/go-spiffe/tree/master/examples/svid-watcher

Index

• Constants
• func Dial(opts ...DialOption) (*grpc.ClientConn, error)
• func DialContext(ctx context.Context, opts ...DialOption) (*grpc.ClientConn, error)
• func GetDefaultAddress() (string, bool)
• func ValidateAddress(addr string) error
• type DialOption
  • func WithAddr(addr string) DialOption
  • func WithGRPCOptions(opts ...grpc.DialOption) DialOption
• type Dialer
  • func NewDialer(opts ...DialOption) (*Dialer, error)
  • func (d *Dialer) Dial() (*grpc.ClientConn, error)
  • func (d *Dialer) DialContext(ctx context.Context) (*grpc.ClientConn, error)
• type X509SVID
• type X509SVIDClient
  • func NewX509SVIDClient(watcher X509SVIDWatcher, opts ...DialOption) (*X509SVIDClient, error)
  • func (c *X509SVIDClient) Start() error
  • func (c *X509SVIDClient) Stop() error
• type X509SVIDWatcher
• type X509SVIDs
  • func (x *X509SVIDs) Default() *X509SVID

Constants

const SocketEnv = "SPIFFE_ENDPOINT_SOCKET"

SocketEnv is the environment variable holding the default Workload API address.

Functions

func Dial

func Dial(opts ...DialOption) (*grpc.ClientConn, error)

Dial creates a gRPC client connection using a background context and the given dial options.

func DialContext

func DialContext(ctx context.Context, opts ...DialOption) (*grpc.ClientConn, error)

DialContext creates a gRPC client connection using the given context and dial options.

func GetDefaultAddress

func GetDefaultAddress() (string, bool)

GetDefaultAddress retrieves the value of the SocketEnv environment variable.

func ValidateAddress

func ValidateAddress(addr string) error

ValidateAddress verifies addr can be parsed as a URL structure and matches the required scheme validations.

Types

type DialOption

type DialOption func(*dialConfig)

DialOption is a function type used to configure a Dialer.

func WithAddr

func WithAddr(addr string) DialOption

WithAddr returns a DialOption that sets the dial address to the given value.

func WithGRPCOptions

func WithGRPCOptions(opts ...grpc.DialOption) DialOption

WithGRPCOptions returns a DialOption that appends the given gRPC DialOptions.

type Dialer

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

Dialer type is used to create client gRPC connections.

func NewDialer

func NewDialer(opts ...DialOption) (*Dialer, error)

NewDialer creates a Dialer configured according to the given DialOption list.

func (*Dialer) Dial

func (d *Dialer) Dial() (*grpc.ClientConn, error)

Dial calls DialContext using a background context.

func (*Dialer) DialContext

func (d *Dialer) DialContext(ctx context.Context) (*grpc.ClientConn, error)

DialContext is a wrapper of grpc.DialContext that uses the target and dial options defined in Dialer.

type X509SVID

type X509SVID struct {
	SPIFFEID                  string
	PrivateKey                crypto.Signer
	Certificates              []*x509.Certificate
	TrustBundle               []*x509.Certificate
	TrustBundlePool           *x509.CertPool
	FederatedTrustBundles     map[string][]*x509.Certificate
	FederatedTrustBundlePools map[string]*x509.CertPool
}

SVID is an X.509 SPIFFE Verifiable Identity Document.

See https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md

type X509SVIDClient

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

X509SVIDClient interacts with the SPIFFE Workload API.

func NewX509SVIDClient

func NewX509SVIDClient(watcher X509SVIDWatcher, opts ...DialOption) (*X509SVIDClient, error)

NewX509SVIDClient returns a new Workload API client for X.509 SVIDs.

func (*X509SVIDClient) Start

func (c *X509SVIDClient) Start() error

Start starts the client.

The client will always start, and users should rely on the watcher interface to receives updates on the client's status.

It is an error to call Start() more than once. Calling Start() after Stop() is not supported.

func (*X509SVIDClient) Stop

func (c *X509SVIDClient) Stop() error

Stop stops the client and waits for the watch loop to end.

type X509SVIDWatcher

type X509SVIDWatcher interface {
	// UpdateX509SVIDs indicates to the Watcher that the SVID has been updated
	UpdateX509SVIDs(*X509SVIDs)

	// OnError indicates an error occurred.
	OnError(err error)
}

X509SVIDWatcher is implemented by consumers who wish to be updated on SVID changes.

type X509SVIDs

type X509SVIDs struct {
	// SVIDs is a list of X509SVID messages, each of which includes a single
	// SPIFFE Verifiable Identity Document, along with its private key and bundle.
	SVIDs []*X509SVID

	// CRL is a list of revoked certificates.
	// Unimplemented.
	CRL *pkix.CertificateList
}

X509SVIDs is an X.509 SVID response from the SPIFFE Workload API.

func (*X509SVIDs) Default

func (x *X509SVIDs) Default() *X509SVID

Default returns the default SVID (the first in the list).

See the SPIFFE Workload API standard Section 5.3 (https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE_Workload_API.md#53-default-identity)