workloadapi

package
v2.1.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 6, 2023 License: Apache-2.0 Imports: 25 Imported by: 144

Documentation

Index

Examples

Constants

View Source
const (
	// SocketEnv is the environment variable holding the default Workload API
	// address.
	SocketEnv = "SPIFFE_ENDPOINT_SOCKET"
)

Variables

View Source
var (
	ErrInvalidEndpointScheme = errors.New("workload endpoint socket URI must have a \"tcp\" or \"unix\" scheme")
)

Functions

func FetchJWTBundles

func FetchJWTBundles(ctx context.Context, options ...ClientOption) (*jwtbundle.Set, error)

FetchJWTBundles fetches the JWT bundles for JWT-SVID validation, keyed by a SPIFFE ID of the trust domain to which they belong.

func FetchJWTSVID

func FetchJWTSVID(ctx context.Context, params jwtsvid.Params, options ...ClientOption) (*jwtsvid.SVID, error)

FetchJWTSVID fetches a JWT-SVID.

Example
package main

import (
	"context"

	"github.com/spiffe/go-spiffe/v2/spiffeid"
	"github.com/spiffe/go-spiffe/v2/svid/jwtsvid"
	"github.com/spiffe/go-spiffe/v2/workloadapi"
)

func main() {
	serverID, err := spiffeid.FromString("spiffe://example.org/server")
	if err != nil {
		// TODO: error handling
	}

	svid, err := workloadapi.FetchJWTSVID(context.TODO(), jwtsvid.Params{
		Audience: serverID.String(),
	})
	if err != nil {
		// TODO: error handling
	}

	// TODO: use the JWT-SVID
	svid = svid
}
Output:

func FetchJWTSVIDs added in v2.1.0

func FetchJWTSVIDs(ctx context.Context, params jwtsvid.Params, options ...ClientOption) ([]*jwtsvid.SVID, error)

FetchJWTSVID fetches all JWT-SVIDs.

func FetchX509Bundles

func FetchX509Bundles(ctx context.Context, options ...ClientOption) (*x509bundle.Set, error)

FetchX509Bundle fetches the X.509 bundles.

func FetchX509SVID

func FetchX509SVID(ctx context.Context, options ...ClientOption) (*x509svid.SVID, error)

FetchX509SVID fetches the default X509-SVID, i.e. the first in the list returned by the Workload API.

Example
package main

import (
	"context"

	"github.com/spiffe/go-spiffe/v2/workloadapi"
)

func main() {
	svid, err := workloadapi.FetchX509SVID(context.TODO())
	if err != nil {
		// TODO: error handling
	}

	// TODO: use the X509-SVID
	svid = svid
}
Output:

func FetchX509SVIDs

func FetchX509SVIDs(ctx context.Context, options ...ClientOption) ([]*x509svid.SVID, error)

FetchX509SVIDs fetches all X509-SVIDs.

func GetDefaultAddress

func GetDefaultAddress() (string, bool)

func ValidateAddress

func ValidateAddress(addr string) error

ValidateAddress validates that the provided address can be parsed to a gRPC target string for dialing a Workload API endpoint exposed as either a Unix Domain Socket or TCP socket.

func ValidateJWTSVID

func ValidateJWTSVID(ctx context.Context, token, audience string, options ...ClientOption) (*jwtsvid.SVID, error)

ValidateJWTSVID validates the JWT-SVID token. The parsed and validated JWT-SVID is returned.

Example
package main

import (
	"context"

	"github.com/spiffe/go-spiffe/v2/spiffeid"
	"github.com/spiffe/go-spiffe/v2/workloadapi"
)

func main() {
	serverID, err := spiffeid.FromString("spiffe://example.org/server")
	if err != nil {
		// TODO: error handling
	}

	token := "TODO"
	svid, err := workloadapi.ValidateJWTSVID(context.TODO(), token, serverID.String())
	if err != nil {
		// TODO: error handling
	}

	// TODO: use the JWT-SVID
	svid = svid
}
Output:

func WatchJWTBundles

func WatchJWTBundles(ctx context.Context, watcher JWTBundleWatcher, options ...ClientOption) error

WatchJWTBundles watches for changes to the JWT bundles.

func WatchX509Bundles added in v2.1.0

func WatchX509Bundles(ctx context.Context, watcher X509BundleWatcher, options ...ClientOption) error

WatchX509Bundles watches for changes to the X.509 bundles.

func WatchX509Context

func WatchX509Context(ctx context.Context, watcher X509ContextWatcher, options ...ClientOption) error

WatchX509Context watches for updates to the X.509 context.

Types

type BundleSource

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

BundleSource is a source of SPIFFE bundles maintained via the Workload API.

func NewBundleSource

func NewBundleSource(ctx context.Context, options ...BundleSourceOption) (_ *BundleSource, err error)

NewBundleSource creates a new BundleSource. It blocks until the initial update has been received from the Workload API. The source should be closed when no longer in use to free underlying resources.

func (*BundleSource) Close

func (s *BundleSource) Close() error

Close closes the source, dropping the connection to the Workload API. Other source methods will return an error after Close has been called. The underlying Workload API client will also be closed if it is owned by the BundleSource (i.e. not provided via the WithClient option).

func (*BundleSource) GetBundleForTrustDomain

func (s *BundleSource) GetBundleForTrustDomain(trustDomain spiffeid.TrustDomain) (*spiffebundle.Bundle, error)

GetBundleForTrustDomain returns the SPIFFE bundle for the given trust domain. It implements the spiffebundle.Source interface.

func (*BundleSource) GetJWTBundleForTrustDomain

func (s *BundleSource) GetJWTBundleForTrustDomain(trustDomain spiffeid.TrustDomain) (*jwtbundle.Bundle, error)

GetJWTBundleForTrustDomain returns the JWT bundle for the given trust domain. It implements the jwtbundle.Source interface.

func (*BundleSource) GetX509BundleForTrustDomain

func (s *BundleSource) GetX509BundleForTrustDomain(trustDomain spiffeid.TrustDomain) (*x509bundle.Bundle, error)

GetX509BundleForTrustDomain returns the X.509 bundle for the given trust domain. It implements the x509bundle.Source interface.

func (*BundleSource) Updated

func (s *BundleSource) Updated() <-chan struct{}

Updated returns a channel that is sent on whenever the source is updated.

func (*BundleSource) WaitUntilUpdated

func (s *BundleSource) WaitUntilUpdated(ctx context.Context) error

WaitUntilUpdated waits until the source is updated or the context is done, in which case ctx.Err() is returned.

type BundleSourceOption

type BundleSourceOption interface {
	// contains filtered or unexported methods
}

BundleSourceOption is an option for the BundleSource. A SourceOption is also a BundleSourceOption.

type Client

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

Client is a Workload API client.

func New

func New(ctx context.Context, options ...ClientOption) (*Client, error)

New dials the Workload API and returns a client. The client should be closed when no longer in use to free underlying resources.

func (*Client) Close

func (c *Client) Close() error

Close closes the client.

func (*Client) FetchJWTBundles

func (c *Client) FetchJWTBundles(ctx context.Context) (*jwtbundle.Set, error)

FetchJWTBundles fetches the JWT bundles for JWT-SVID validation, keyed by a SPIFFE ID of the trust domain to which they belong.

func (*Client) FetchJWTSVID

func (c *Client) FetchJWTSVID(ctx context.Context, params jwtsvid.Params) (*jwtsvid.SVID, error)

FetchJWTSVID fetches a JWT-SVID.

func (*Client) FetchJWTSVIDs added in v2.1.0

func (c *Client) FetchJWTSVIDs(ctx context.Context, params jwtsvid.Params) ([]*jwtsvid.SVID, error)

FetchJWTSVIDs fetches all JWT-SVIDs.

func (*Client) FetchX509Bundles

func (c *Client) FetchX509Bundles(ctx context.Context) (*x509bundle.Set, error)

FetchX509Bundles fetches the X.509 bundles.

func (*Client) FetchX509Context

func (c *Client) FetchX509Context(ctx context.Context) (*X509Context, error)

FetchX509Context fetches the X.509 context, which contains both X509-SVIDs and X.509 bundles.

func (*Client) FetchX509SVID

func (c *Client) FetchX509SVID(ctx context.Context) (*x509svid.SVID, error)

FetchX509SVID fetches the default X509-SVID, i.e. the first in the list returned by the Workload API.

func (*Client) FetchX509SVIDs

func (c *Client) FetchX509SVIDs(ctx context.Context) ([]*x509svid.SVID, error)

FetchX509SVIDs fetches all X509-SVIDs.

func (*Client) ValidateJWTSVID

func (c *Client) ValidateJWTSVID(ctx context.Context, token, audience string) (*jwtsvid.SVID, error)

ValidateJWTSVID validates the JWT-SVID token. The parsed and validated JWT-SVID is returned.

func (*Client) WatchJWTBundles

func (c *Client) WatchJWTBundles(ctx context.Context, watcher JWTBundleWatcher) error

WatchJWTBundles watches for changes to the JWT bundles. The watcher receives the updated JWT bundles.

func (*Client) WatchX509Bundles added in v2.1.0

func (c *Client) WatchX509Bundles(ctx context.Context, watcher X509BundleWatcher) error

WatchX509Bundles watches for changes to the X.509 bundles. The watcher receives the updated X.509 bundles.

func (*Client) WatchX509Context

func (c *Client) WatchX509Context(ctx context.Context, watcher X509ContextWatcher) error

WatchX509Context watches for updates to the X.509 context. The watcher receives the updated X.509 context.

type ClientOption

type ClientOption interface {
	// contains filtered or unexported methods
}

ClientOption is an option used when creating a new Client.

func WithAddr

func WithAddr(addr string) ClientOption

WithAddr provides an address for the Workload API. The value of the SPIFFE_ENDPOINT_SOCKET environment variable will be used if the option is unused.

func WithDialOptions

func WithDialOptions(options ...grpc.DialOption) ClientOption

WithDialOptions provides extra GRPC dialing options when dialing the Workload API.

func WithLogger

func WithLogger(logger logger.Logger) ClientOption

WithLogger provides a logger to the Client.

type JWTBundleWatcher

type JWTBundleWatcher interface {
	// OnJWTBundlesUpdate is called with the latest JWT bundle set retrieved
	// from the Workload API.
	OnJWTBundlesUpdate(*jwtbundle.Set)

	// OnJWTBundlesWatchError is called when there is a problem establishing
	// or maintaining connectivity with the Workload API.
	OnJWTBundlesWatchError(error)
}

JWTBundleWatcher receives JWT bundle updates from the Workload API.

type JWTSource

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

JWTSource is a source of JWT-SVID and JWT bundles maintained via the Workload API.

func NewJWTSource

func NewJWTSource(ctx context.Context, options ...JWTSourceOption) (_ *JWTSource, err error)

NewJWTSource creates a new JWTSource. It blocks until the initial update has been received from the Workload API. The source should be closed when no longer in use to free underlying resources.

func (*JWTSource) Close

func (s *JWTSource) Close() error

Close closes the source, dropping the connection to the Workload API. Other source methods will return an error after Close has been called. The underlying Workload API client will also be closed if it is owned by the JWTSource (i.e. not provided via the WithClient option).

func (*JWTSource) FetchJWTSVID

func (s *JWTSource) FetchJWTSVID(ctx context.Context, params jwtsvid.Params) (*jwtsvid.SVID, error)

FetchJWTSVID fetches a JWT-SVID from the source with the given parameters. It implements the jwtsvid.Source interface.

func (*JWTSource) FetchJWTSVIDs added in v2.1.0

func (s *JWTSource) FetchJWTSVIDs(ctx context.Context, params jwtsvid.Params) ([]*jwtsvid.SVID, error)

FetchJWTSVIDs fetches all JWT-SVIDs from the source with the given parameters. It implements the jwtsvid.Source interface.

func (*JWTSource) GetJWTBundleForTrustDomain

func (s *JWTSource) GetJWTBundleForTrustDomain(trustDomain spiffeid.TrustDomain) (*jwtbundle.Bundle, error)

GetJWTBundleForTrustDomain returns the JWT bundle for the given trust domain. It implements the jwtbundle.Source interface.

func (*JWTSource) Updated

func (s *JWTSource) Updated() <-chan struct{}

Updated returns a channel that is sent on whenever the source is updated.

func (*JWTSource) WaitUntilUpdated

func (s *JWTSource) WaitUntilUpdated(ctx context.Context) error

WaitUntilUpdated waits until the source is updated or the context is done, in which case ctx.Err() is returned.

type JWTSourceOption

type JWTSourceOption interface {
	// contains filtered or unexported methods
}

JWTSourceOption is an option for the JWTSource. A SourceOption is also a JWTSourceOption.

type SourceOption

type SourceOption interface {
	// contains filtered or unexported methods
}

SourceOption are options that are shared among all option types.

func WithClient

func WithClient(client *Client) SourceOption

WithClient provides a Client for the source to use. If unset, a new Client will be created.

func WithClientOptions

func WithClientOptions(options ...ClientOption) SourceOption

WithClientOptions controls the options used to create a new Client for the source. This option will be ignored if WithClient is used.

type X509BundleWatcher added in v2.1.0

type X509BundleWatcher interface {
	// OnX509BundlesUpdate is called with the latest X.509 bundle set retrieved
	// from the Workload API.
	OnX509BundlesUpdate(*x509bundle.Set)

	// OnX509BundlesWatchError is called when there is a problem establishing
	// or maintaining connectivity with the Workload API.
	OnX509BundlesWatchError(error)
}

X509BundleWatcher receives X.509 bundle updates from the Workload API.

type X509Context

type X509Context struct {
	// SVIDs is a list of workload X509-SVIDs.
	SVIDs []*x509svid.SVID

	// Bundles is a set of X.509 bundles.
	Bundles *x509bundle.Set
}

X509Context conveys X.509 materials from the Workload API.

func FetchX509Context

func FetchX509Context(ctx context.Context, options ...ClientOption) (*X509Context, error)

FetchX509Context fetches the X.509 context, which contains both X509-SVIDs and X.509 bundles.

func (*X509Context) DefaultSVID

func (x *X509Context) DefaultSVID() *x509svid.SVID

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

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

type X509ContextWatcher

type X509ContextWatcher interface {
	// OnX509ContextUpdate is called with the latest X.509 context retrieved
	// from the Workload API.
	OnX509ContextUpdate(*X509Context)

	// OnX509ContextWatchError is called when there is a problem establishing
	// or maintaining connectivity with the Workload API.
	OnX509ContextWatchError(error)
}

X509ContextWatcher receives X509Context updates from the Workload API.

type X509Source

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

X509Source is a source of X509-SVIDs and X.509 bundles maintained via the Workload API.

func NewX509Source

func NewX509Source(ctx context.Context, options ...X509SourceOption) (_ *X509Source, err error)

NewX509Source creates a new X509Source. It blocks until the initial update has been received from the Workload API. The source should be closed when no longer in use to free underlying resources.

func (*X509Source) Close

func (s *X509Source) Close() (err error)

Close closes the source, dropping the connection to the Workload API. Other source methods will return an error after Close has been called. The underlying Workload API client will also be closed if it is owned by the X509Source (i.e. not provided via the WithClient option).

func (*X509Source) GetX509BundleForTrustDomain

func (s *X509Source) GetX509BundleForTrustDomain(trustDomain spiffeid.TrustDomain) (*x509bundle.Bundle, error)

GetX509BundleForTrustDomain returns the X.509 bundle for the given trust domain. It implements the x509bundle.Source interface.

func (*X509Source) GetX509SVID

func (s *X509Source) GetX509SVID() (*x509svid.SVID, error)

GetX509SVID returns an X509-SVID from the source. It implements the x509svid.Source interface.

func (*X509Source) Updated

func (s *X509Source) Updated() <-chan struct{}

Updated returns a channel that is sent on whenever the source is updated.

func (*X509Source) WaitUntilUpdated

func (s *X509Source) WaitUntilUpdated(ctx context.Context) error

WaitUntilUpdated waits until the source is updated or the context is done, in which case ctx.Err() is returned.

type X509SourceOption

type X509SourceOption interface {
	// contains filtered or unexported methods
}

X509SourceOption is an option for the X509Source. A SourceOption is also an X509SourceOption.

func WithDefaultX509SVIDPicker

func WithDefaultX509SVIDPicker(picker func([]*x509svid.SVID) *x509svid.SVID) X509SourceOption

WithDefaultX509SVIDPicker provides a function that is used to determine the default X509-SVID when more than one is provided by the Workload API. By default, the first X509-SVID in the list returned by the Workload API is used.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL