Documentation
¶
Overview ¶
Package spiffe implements the X.509-SVID identity boundary of the Secure Runtime (ADR-011): every fenced gRPC peer presents a certificate whose SPIFFE ID names its exact principal, and every boundary verifies the chain against the trust bundle and matches the presented identity against the claims of the request. Identity shape:
spiffe://<trust-domain>/ns/<tenant>/worker/<runtime-instance>
The control plane's own identity is spiffe://<trust-domain>/ns/system/control.
Index ¶
- Constants
- func CheckPeerIdentity(ctx context.Context, pattern Pattern) error
- func ControlPlaneIdentity(trustDomain string) string
- func Identity(trustDomain, tenantID, instanceID string) string
- func ParseLeaf(certificate tls.Certificate) (*x509.Certificate, error)
- func ParsePeerIdentity(cert *x509.Certificate) (string, error)
- func PeerIdentity(ctx context.Context) (string, error)
- func PeerWorkerClaims(ctx context.Context) (trustDomain, tenantID, instanceID string, err error)
- func TrustBundlePool(pemCerts [][]byte) (*x509.CertPool, error)
- func WorkerClaims(identity string) (trustDomain, tenantID, instanceID string, err error)
- type CA
- func (c *CA) Certificate() *x509.Certificate
- func (c *CA) IssueSVID(tenantID, instanceID string, now time.Time, validity time.Duration) (tls.Certificate, error)
- func (c *CA) IssueSVIDFor(identity string, now time.Time, validity time.Duration) (tls.Certificate, error)
- func (c *CA) IssueSVIDWithSANs(identity string, now time.Time, validity time.Duration, dnsNames []string, ...) (tls.Certificate, error)
- func (c *CA) PEM() []byte
- func (c *CA) TrustDomain() string
- type Pattern
Constants ¶
const DefaultTrustDomain = "fenced.dev"
DefaultTrustDomain is the agent OS trust domain.
const SystemNamespace = "system"
SystemNamespace is the SPIFFE namespace of the control plane itself.
Variables ¶
This section is empty.
Functions ¶
func CheckPeerIdentity ¶
CheckPeerIdentity verifies that the caller's SPIFFE ID matches the pattern.
func ControlPlaneIdentity ¶
ControlPlaneIdentity renders the SPIFFE ID of the control plane itself.
func ParseLeaf ¶
func ParseLeaf(certificate tls.Certificate) (*x509.Certificate, error)
ParseLeaf parses the leaf of an issued SVID (tests and tooling).
func ParsePeerIdentity ¶
func ParsePeerIdentity(cert *x509.Certificate) (string, error)
ParsePeerIdentity extracts the SPIFFE ID from a peer's verified X.509-SVID (first certificate in the presented chain). It returns an error when the peer did not present a TLS certificate or its leaf has no single SPIFFE URI SAN.
func PeerIdentity ¶
PeerIdentity extracts the SPIFFE ID of the gRPC peer from the context.
func PeerWorkerClaims ¶
PeerWorkerClaims extracts an exact worker identity from the verified gRPC peer certificate.
func TrustBundlePool ¶
TrustBundlePool builds an x509.CertPool from PEM certificates.
func WorkerClaims ¶
WorkerClaims parses the tenant and runtime instance from an exact worker SPIFFE ID. It rejects wildcard patterns and non-worker identities.
Types ¶
type CA ¶
type CA struct {
// contains filtered or unexported fields
}
CA is a self-signed SPIFFE certificate authority for one trust domain.
func NewCA ¶
NewCA creates a fresh CA for the trust domain. Dev/deployments generate one with fenced-svid; production rotates it through a real CA process.
func (*CA) Certificate ¶
func (c *CA) Certificate() *x509.Certificate
Certificate returns the CA certificate.
func (*CA) IssueSVID ¶
func (c *CA) IssueSVID(tenantID, instanceID string, now time.Time, validity time.Duration) (tls.Certificate, error)
IssueSVID issues an X.509-SVID for the principal spiffe://<trust-domain>/ns/<tenant>/worker/<instance>. The SVID is dual-purpose (client and server authentication) so the control plane can use one for its listener and workers for their client connections.
func (*CA) IssueSVIDFor ¶
func (c *CA) IssueSVIDFor(identity string, now time.Time, validity time.Duration) (tls.Certificate, error)
IssueSVIDFor issues an X.509-SVID for an explicit SPIFFE ID in this trust domain, e.g. the control plane identity spiffe://<domain>/ns/system/control.
func (*CA) IssueSVIDWithSANs ¶
func (c *CA) IssueSVIDWithSANs(identity string, now time.Time, validity time.Duration, dnsNames []string, ipAddresses []net.IP) (tls.Certificate, error)
IssueSVIDWithSANs issues an SVID with additional DNS/IP subject alternatives so it can serve TLS endpoints (loopback development, load balancer DNS names). The SPIFFE URI SAN remains the identity anchor; the extra SANs only satisfy transport-level name verification.
func (*CA) TrustDomain ¶
TrustDomain returns the CA's trust domain.
type Pattern ¶
Pattern is an SPIFFE ID allow pattern; "*" matches any segment.
func ParsePattern ¶
ParsePattern parses "spiffe://<trust-domain>/ns/<tenant>/worker/<instance>" with "*" wildcards, e.g. "spiffe://fenced.dev/ns/*/worker/*".
Source Files