workloadapi

package
v2.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2024 License: Apache-2.0 Imports: 24 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 Backoff added in v2.4.0 

type Backoff interface {
	// Next returns the next backoff period.
	Next() time.Duration

	// Reset() resets the backoff.
	Reset()
}

Backoff provides backoff for a workload API operation.

type BackoffStrategy added in v2.4.0 

type BackoffStrategy interface {
	// NewBackoff returns a new backoff for the strategy. The returned
	// Backoff is in the same state that it would be in after a call to
	// Reset().
	NewBackoff() Backoff
}

BackoffStrategy provides backoff facilities.

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 WithBackoffStrategy added in v2.4.0 

func WithBackoffStrategy(backoffStrategy BackoffStrategy) ClientOption

WithBackoff provides a custom backoff strategy that replaces the default backoff strategy (linear backoff).

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.

func WithDefaultJWTSVIDPicker added in v2.4.0 

func WithDefaultJWTSVIDPicker(picker func([]*jwtsvid.SVID) *jwtsvid.SVID) JWTSourceOption

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

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.