The highest tagged major version is
Documentation
¶
Overview ¶
Package spiffe provides a way to make workloads to get automatically rotated X.509 SVIDs from a SPIFFE Workload API and to use them to establish mTLS connections with other workloads.
The functions ListenTLS and DialTLS provides a handy way to get and use the SVIDs for mTLS connections. If more control over the connections is needed, use the TLSPeer type instead.
A full example is available at: https://github.com/spiffe/go-spiffe/tree/master/examples/svid-mTLS
Index ¶
- func AdaptGetCertificate(p *TLSPeer) func(*tls.ClientHelloInfo) (*tls.Certificate, error)
- func AdaptGetClientCertificate(p *TLSPeer) func(*tls.CertificateRequestInfo) (*tls.Certificate, error)
- func AdaptVerifyPeerCertificate(p *TLSPeer, expectPeer ExpectPeerFunc) func([][]byte, [][]*x509.Certificate) error
- func DialTLS(ctx context.Context, network, addr string, expectPeer ExpectPeerFunc) (net.Conn, error)
- func ListenTLS(ctx context.Context, network, addr string, expectPeer ExpectPeerFunc) (net.Listener, error)
- func MatchID(ids []string, cert *x509.Certificate) error
- func NormalizeID(id string, mode ValidationMode) (string, error)
- func NormalizeURI(u *url.URL, mode ValidationMode) (*url.URL, error)
- func ParseID(spiffeID string, mode ValidationMode) (*url.URL, error)
- func TrustDomainID(trustDomain string) string
- func TrustDomainURI(trustDomain string) *url.URL
- func ValidateID(spiffeID string, mode ValidationMode) error
- func ValidateURI(id *url.URL, mode ValidationMode) error
- func VerifyCertificate(leaf *x509.Certificate, intermediates *x509.CertPool, roots *x509.CertPool) error
- func VerifyPeerCertificate(peerChain []*x509.Certificate, trustDomainRoots map[string]*x509.CertPool, ...) ([][]*x509.Certificate, error)
- func WithLogger(log Logger) func(*TLSPeer) error
- func WithWorkloadAPIAddr(addr string) func(*TLSPeer) error
- type ExpectPeerFunc
- type Logger
- type TLSPeer
- func (p *TLSPeer) Close() error
- func (p *TLSPeer) Dial(ctx context.Context, network, address string, expectPeer ExpectPeerFunc) (net.Conn, error)
- func (p *TLSPeer) DialGRPC(ctx context.Context, addr string, expectPeer ExpectPeerFunc, ...) (*grpc.ClientConn, error)
- func (p *TLSPeer) GetCertificate() (*tls.Certificate, error)
- func (p *TLSPeer) GetConfig(ctx context.Context, expectPeer ExpectPeerFunc) (*tls.Config, error)
- func (p *TLSPeer) GetRoots() (map[string]*x509.CertPool, error)
- func (p *TLSPeer) Listen(ctx context.Context, network, address string, expectPeer ExpectPeerFunc) (net.Listener, error)
- func (p *TLSPeer) NewListener(ctx context.Context, inner net.Listener, expectPeer ExpectPeerFunc) (net.Listener, error)
- func (p *TLSPeer) WaitUntilReady(ctx context.Context) error
- type TLSPeerOption
- type ValidationMode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AdaptGetCertificate ¶
func AdaptGetCertificate(p *TLSPeer) func(*tls.ClientHelloInfo) (*tls.Certificate, error)
AdaptGetCertificate is a convenience function used to adapt a TLSPeer to the tls.Config GetCertificate callback.
func AdaptGetClientCertificate ¶
func AdaptGetClientCertificate(p *TLSPeer) func(*tls.CertificateRequestInfo) (*tls.Certificate, error)
AdaptGetClientCertificate is a convenience function used to adapt a TLSPeer to the tls.Config GetClientCertificate callback.
func AdaptVerifyPeerCertificate ¶
func AdaptVerifyPeerCertificate(p *TLSPeer, expectPeer ExpectPeerFunc) func([][]byte, [][]*x509.Certificate) error
AdaptVerifyPeerCertificate is a convenience function used to adapt a TLSPeer to the tls.Config VerifyPeerCertificate callback. It uses the VerifyPeerCertificate function from this package under the covers, using roots obtained from the TLS peer. The expectPeer callback is used to verify remote peer SPIFFE IDs.
func DialTLS ¶
func DialTLS(ctx context.Context, network, addr string, expectPeer ExpectPeerFunc) (net.Conn, error)
DialTLS is a convenience wrapper for dialing remote peers using credentials obtained from the workload API. If more control is required it is recommended to use the TLSPeer instead.
func ListenTLS ¶
func ListenTLS(ctx context.Context, network, addr string, expectPeer ExpectPeerFunc) (net.Listener, error)
ListenTLS is a convenience wrapper for listening for remote peers using credentials obtained from the workload API. If more control is required it is recomended to use the TLSPeer instead.
func MatchID ¶
func MatchID(ids []string, cert *x509.Certificate) error
MatchID tries to match a SPIFFE ID, given a certificate
func NormalizeID ¶
func NormalizeID(id string, mode ValidationMode) (string, error)
NormalizeID normalizes the SPIFFE ID so it can be directly compared for equality. Specifically, it lower cases the scheme and host portions of the URI.
func NormalizeURI ¶
NormalizeURI normalizes the SPIFFE ID URI so it can be directly compared for equality. Specifically, it lower cases the scheme and host portions of the URI.
func ParseID ¶
func ParseID(spiffeID string, mode ValidationMode) (*url.URL, error)
ParseID parses the SPIFFE ID and makes sure it is valid according to the specified validation mode.
func TrustDomainID ¶
TrustDomainID creates a trust domain SPIFFE ID given a trust domain.
func TrustDomainURI ¶
TrustDomainURI creates a trust domain SPIFFE URI given a trust domain.
func ValidateID ¶
func ValidateID(spiffeID string, mode ValidationMode) error
ValidateID validates the SPIFFE ID according to the SPIFFE specification. The validation mode controls the type of validation.
func ValidateURI ¶
func ValidateURI(id *url.URL, mode ValidationMode) error
ValidateURI validates the SPIFFE ID according to the SPIFFE specification, namely: - spiffe id is not empty - spiffe id is a valid url - scheme is 'spiffe' - user info is not allowed - host is not empty - port is not allowed - query values are not allowed - fragment is not allowed In addition, the validation mode is used to control what kind of SPIFFE ID is expected. For more information: [https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE-ID.md]
func VerifyCertificate ¶
func VerifyCertificate(leaf *x509.Certificate, intermediates *x509.CertPool, roots *x509.CertPool) error
Verify a SPIFFE certificate and its certification path. This function does not perform rich validation and is deprecated. Use VerifyPeerCertificate() instead.
func VerifyPeerCertificate ¶
func VerifyPeerCertificate(peerChain []*x509.Certificate, trustDomainRoots map[string]*x509.CertPool, expectPeerFn ExpectPeerFunc) ([][]*x509.Certificate, error)
VerifyPeerCertificate verifies the provided peer certificate chain using the set trust domain roots. The expectPeerFn callback is used to check the peer ID after the chain of trust has been verified to assert that the chain belongs to the intended peer.
func WithLogger ¶
WithLogger provides a logger to the TLSPeer
func WithWorkloadAPIAddr ¶
WithWorkloadAPIAddr overrides the address used to reach the SPIFFE Workload API. By default, the SPIFFE_ENDPOINT_SOCKET environment variable is used to convey the address.
Types ¶
type ExpectPeerFunc ¶
type ExpectPeerFunc func(peerID string, verifiedChains [][]*x509.Certificate) error
ExpectPeerFunc is invoked after peer SVID verification to validate the SVID belongs to th indended peer. If an error is returned, verification (i.e. TLS handshake) fails.
func ExpectPeer ¶
func ExpectPeer(expectedID string) ExpectPeerFunc
ExpectPeer allows a peer matching the specified peer ID
func ExpectPeerInDomain ¶
func ExpectPeerInDomain(expectedDomain string) ExpectPeerFunc
ExpectPeerInDomain returns a callback that asserts that the peer ID belongs to the provided trust domain (i.e. "domain.test")
func ExpectPeers ¶
func ExpectPeers(expectedIDs ...string) ExpectPeerFunc
ExpectPeers allows any peer to belong to the provided set.
type Logger ¶
type Logger interface {
Debugf(format string, args ...interface{})
Infof(format string, args ...interface{})
Warnf(format string, args ...interface{})
Errorf(format string, args ...interface{})
}
Logger is a logging interface used to log information
type TLSPeer ¶
type TLSPeer struct {
// contains filtered or unexported fields
}
TLSPeer connects to the workload API and provides up-to-date identity and trusted roots for TLS dialing and listening.
func NewTLSPeer ¶
func NewTLSPeer(opts ...TLSPeerOption) (*TLSPeer, error)
NewTLSPeer creates a new TLSPeer using the provided options.
func (*TLSPeer) Close ¶
Close closes the TLSPeer. It stops listening to Workload API updates. Any configuration obtained from the TLSPeer (directly or indirectly) is still valid but will no longer stay up-to-date.
func (*TLSPeer) Dial ¶
func (p *TLSPeer) Dial(ctx context.Context, network, address string, expectPeer ExpectPeerFunc) (net.Conn, error)
Dial dials to a remote peer using the network and address provided. It returns a TLS connection. If the remote peer does not have a SPIFFE ID allowable by the expectPeer callback, the TLS handshake will fail.
func (*TLSPeer) DialGRPC ¶
func (p *TLSPeer) DialGRPC(ctx context.Context, addr string, expectPeer ExpectPeerFunc, opts ...grpc.DialOption) (*grpc.ClientConn, error)
DialGRPC dials the gRPC endpoint addr using the peer TLS configuration.
func (*TLSPeer) GetCertificate ¶
func (p *TLSPeer) GetCertificate() (*tls.Certificate, error)
GetCertificate returns the TLS certificate returned from the Workload API. It fails if no certificate has been obtained. Call WaitUntilReady() first to ensure this call will succeed.
func (*TLSPeer) GetConfig ¶
GetConfig returns th peer TLS configuration that can be used to dial or listen for remote peers. The remote peer SPIFFE ID must be allowed by the provided expectPeer callback or the TLS handshake will fail. This function blocks until the peer is ready (see WaitUntilReady).
func (*TLSPeer) GetRoots ¶
GetRoots returns a map from trust domain ID (i.e. spiffe://domain.test) to trusted roots pool returned from the Workload API. It fails if no roots have been obtain. Call WaitUntilReady() first to ensure this call will succeed.
func (*TLSPeer) Listen ¶
func (p *TLSPeer) Listen(ctx context.Context, network, address string, expectPeer ExpectPeerFunc) (net.Listener, error)
Listen starts listening for remote peers using the network and address provided. It returns a listener, which should closed when finished to release resources.
type TLSPeerOption ¶
type ValidationMode ¶
type ValidationMode interface {
// contains filtered or unexported methods
}
ValidationMode is used to control extra validation of the SPIFFE ID beyond the syntax checks done during parsing/validation.
func AllowAnyTrustDomain ¶
func AllowAnyTrustDomain() ValidationMode
Allows a well-formed SPIFFE ID for any trust domain (e.g. spiffe://domain.test).
func AllowAnyTrustDomainWorkload ¶
func AllowAnyTrustDomainWorkload() ValidationMode
Allows a well-formed SPIFFE ID for a workload belonging to any trust domain (e.g. spiffe://domain.test/workload).
func AllowTrustDomain ¶
func AllowTrustDomain(trustDomain string) ValidationMode
Allows a well-formed SPIFFE ID for the specific trust domain (e.g. spiffe://domain.test)
func AllowTrustDomainWorkload ¶
func AllowTrustDomainWorkload(trustDomain string) ValidationMode
Allows a well-formed SPIFFE ID for a workload belonging to a specific trust domain (e.g. spiffe://domain.test/workload)
Source Files