federation

Documentation

Index

• func FetchBundle(ctx context.Context, trustDomain spiffeid.TrustDomain, url string, ...) (*spiffebundle.Bundle, error)
• func NewHandler(trustDomain spiffeid.TrustDomain, source spiffebundle.Source, ...) (http.Handler, error)
• func WatchBundle(ctx context.Context, trustDomain spiffeid.TrustDomain, url string, ...) error
• type BundleWatcher
• type FetchOption
  • func WithSPIFFEAuth(bundleSource x509bundle.Source, endpointID spiffeid.ID) FetchOption
  • func WithWebPKIRoots(rootCAs *x509.CertPool) FetchOption
• type HandlerOption
  • func WithLogger(log logger.Logger) HandlerOption

Examples

• FetchBundle (SPIFFEAuth)
• FetchBundle (WebPKI)
• WatchBundle (SPIFFEAuth)
• WatchBundle (WebPKI)

Functions

func FetchBundle

func FetchBundle(ctx context.Context, trustDomain spiffeid.TrustDomain, url string, option ...FetchOption) (*spiffebundle.Bundle, error)

FetchBundle retrieves a bundle from a bundle endpoint.

Example (SPIFFEAuth)

package main

import (
	"context"

	"github.com/spiffe/go-spiffe/v2/bundle/spiffebundle"
	"github.com/spiffe/go-spiffe/v2/federation"
	"github.com/spiffe/go-spiffe/v2/spiffeid"
)

func main() {
	// Obtain a bundle from the example.org trust domain from a server hosted
	// at https://example.org/bundle with the
	// spiffe://example.org/bundle-server SPIFFE ID.
	endpointURL := "https://example.org:8443/bundle"
	trustDomain, err := spiffeid.TrustDomainFromString("example.org")
	if err != nil {
		// TODO: handle error
	}
	serverID := spiffeid.RequireFromPath(trustDomain, "/bundle-server")

	bundle, err := spiffebundle.Load(trustDomain, "bundle.json")
	if err != nil {
		// TODO: handle error
	}

	bundleSet := spiffebundle.NewSet(bundle)
	bundleSet.Add(bundle)

	updatedBundle, err := federation.FetchBundle(context.TODO(), trustDomain, endpointURL,
		federation.WithSPIFFEAuth(bundleSet, serverID))
	if err != nil {
		// TODO: handle error
	}

	// TODO: use bundle, e.g. replace the bundle in the bundle set so it can
	// be used to fetch the next bundle.
	bundleSet.Add(updatedBundle)
}

Example (WebPKI)

package main

import (
	"context"

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

func main() {
	endpointURL := "https://example.org:8443/bundle"
	trustDomain, err := spiffeid.TrustDomainFromString("example.org")
	if err != nil {
		// TODO: handle error
	}

	bundle, err := federation.FetchBundle(context.TODO(), trustDomain, endpointURL)
	if err != nil {
		// TODO: handle error
	}

	// TODO: use bundle
	bundle = bundle
}

func NewHandler

func NewHandler(trustDomain spiffeid.TrustDomain, source spiffebundle.Source, opts ...HandlerOption) (http.Handler, error)

NewHandler returns an HTTP handler that provides the trust domain bundle for the given trust domain. The bundle is encoded according to the format outlined in the SPIFFE Trust Domain and Bundle specification. The bundle source is used to obtain the bundle on each request. Source implementations should consider a caching strategy if retrieval is expensive. See the specification for more details: https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Trust_Domain_and_Bundle.md

func WatchBundle

func WatchBundle(ctx context.Context, trustDomain spiffeid.TrustDomain, url string, watcher BundleWatcher, options ...FetchOption) error

WatchBundle watches a bundle on a bundle endpoint. It returns when the context is canceled, returning ctx.Err().

Example (SPIFFEAuth)

package main

import (
	"context"

	"github.com/spiffe/go-spiffe/v2/bundle/spiffebundle"
	"github.com/spiffe/go-spiffe/v2/federation"
	"github.com/spiffe/go-spiffe/v2/spiffeid"
)

func main() {
	// Watch for bundle updates from the example.org trust domain from a server
	// hosted at https://example.org/bundle with the
	// spiffe://example.org/bundle-server SPIFFE ID.
	endpointURL := "https://example.org:8443/bundle"
	trustDomain, err := spiffeid.TrustDomainFromString("example.org")
	if err != nil {
		// TODO: handle error
	}
	serverID := spiffeid.RequireFromPath(trustDomain, "/bundle-server")

	bundle, err := spiffebundle.Load(trustDomain, "bundle.json")
	if err != nil {
		// TODO: handle error
	}

	bundleSet := spiffebundle.NewSet(bundle)
	bundleSet.Add(bundle)

	// TODO: When implementing the watcher's OnUpdate, replace the bundle for
	// the trust domain in the bundle set so the next connection uses the
	// updated bundle.
	var watcher federation.BundleWatcher

	err = federation.WatchBundle(context.TODO(), trustDomain, endpointURL,
		watcher, federation.WithSPIFFEAuth(bundleSet, serverID))
	if err != nil {
		// TODO: handle error
	}
}

Example (WebPKI)

package main

import (
	"context"

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

func main() {
	endpointURL := "https://example.org:8443/bundle"
	trustDomain, err := spiffeid.TrustDomainFromString("example.org")
	if err != nil {
		// TODO: handle error
	}

	var watcher federation.BundleWatcher
	err = federation.WatchBundle(context.TODO(), trustDomain, endpointURL, watcher)
	if err != nil {
		// TODO: handle error
	}
}

Types

type BundleWatcher

type BundleWatcher interface {
	// NextRefresh is called by WatchBundle to determine when the next refresh
	// should take place. A refresh hint is provided, which can be zero, meaning
	// the watcher is free to choose its own refresh cadence. If the refresh hint
	// is greater than zero, the watcher SHOULD return a next refresh time at or
	// below that to ensure the bundle stays up-to-date.
	NextRefresh(refreshHint time.Duration) time.Duration

	// OnUpdate is called when a bundle has been updated. If a bundle is
	// fetched but has not changed from the previously fetched bundle, OnUpdate
	// will not be called. This function is called synchronously by WatchBundle
	// and therefore should have a short execution time to prevent blocking the
	// watch.
	OnUpdate(*spiffebundle.Bundle)

	// OnError is called if there is an error fetching the bundle from the
	// endpoint. This function is called synchronously by WatchBundle
	// and therefore should have a short execution time to prevent blocking the
	// watch.
	OnError(err error)
}

BundleWatcher is used by WatchBundle to provide the caller with bundle updates and control the next refresh time.

type FetchOption

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

FetchOption is an option used when dialing the bundle endpoint.

func WithSPIFFEAuth

func WithSPIFFEAuth(bundleSource x509bundle.Source, endpointID spiffeid.ID) FetchOption

WithSPIFFEAuth authenticates the bundle endpoint with SPIFFE authentication using the provided root store. It validates that the endpoint presents the expected SPIFFE ID. This option cannot be used in conjuntion with WithWebPKIRoots option.

func WithWebPKIRoots

func WithWebPKIRoots(rootCAs *x509.CertPool) FetchOption

WithWebPKIRoots authenticates the bundle endpoint using Web PKI authentication using the provided X.509 root certificates instead of the system ones. This option cannot be used in conjuntion with WithSPIFFEAuth option.

type HandlerOption

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

func WithLogger

func WithLogger(log logger.Logger) HandlerOption