s2a

package module
v0.1.7 Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2023 License: Apache-2.0 Imports: 20 Imported by: 0

README

Secure Session Agent Client Libraries

The Secure Session Agent is a service that enables a workload to offload select operations from the mTLS handshake and protects a workload's private key material from exfiltration. Specifically, the workload asks the Secure Session Agent for the TLS configuration to use during the handshake, to perform private key operations, and to validate the peer certificate chain. The Secure Session Agent's client libraries enable applications to communicate with the Secure Session Agent during the TLS handshake, and to encrypt traffic to the peer after the TLS handshake is complete.

This repository contains the source code for the Secure Session Agent's Go client libraries, which allow gRPC and HTTP Go applications to use the Secure Session Agent.

Documentation

Overview

Package s2a provides the S2A transport credentials used by a gRPC application.

Index

Constants

View Source 
const (
	Unspecified = iota
	ConnectToGoogle
	Spiffe
)

Three types of verification modes.

Variables

This section is empty.

Functions

func NewClientCreds 

func NewClientCreds(opts *ClientOptions) (credentials.TransportCredentials, error)

NewClientCreds returns a client-side transport credentials object that uses the S2A to establish a secure connection with a server.

func NewS2ADialTLSContextFunc 

func NewS2ADialTLSContextFunc(opts *ClientOptions) func(ctx context.Context, network, addr string) (net.Conn, error)

NewS2ADialTLSContextFunc returns a dialer which establishes an MTLS connection using S2A. Example use with http.RoundTripper: 

	dialTLSContext := s2a.NewS2aDialTLSContextFunc(&s2a.ClientOptions{
		S2AAddress:         s2aAddress, // required
	})
 	transport := http.DefaultTransport
 	transport.DialTLSContext = dialTLSContext

func NewServerCreds 

func NewServerCreds(opts *ServerOptions) (credentials.TransportCredentials, error)

NewServerCreds returns a server-side transport credentials object that uses the S2A to establish a secure connection with a client.

Types

type AuthInfo 

type AuthInfo interface {
	// AuthType returns the authentication type.
	AuthType() string
	// ApplicationProtocol returns the application protocol, e.g. "grpc".
	ApplicationProtocol() string
	// TLSVersion returns the TLS version negotiated during the handshake.
	TLSVersion() commonpb.TLSVersion
	// Ciphersuite returns the ciphersuite negotiated during the handshake.
	Ciphersuite() commonpb.Ciphersuite
	// PeerIdentity returns the authenticated identity of the peer.
	PeerIdentity() *commonpb.Identity
	// LocalIdentity returns the local identity of the application used during
	// session setup.
	LocalIdentity() *commonpb.Identity
	// PeerCertFingerprint returns the SHA256 hash of the peer certificate used in
	// the S2A handshake.
	PeerCertFingerprint() []byte
	// LocalCertFingerprint returns the SHA256 hash of the local certificate used
	// in the S2A handshake.
	LocalCertFingerprint() []byte
	// IsHandshakeResumed returns true if a cached session was used to resume
	// the handshake.
	IsHandshakeResumed() bool
	// SecurityLevel returns the security level of the connection.
	SecurityLevel() credentials.SecurityLevel
}

AuthInfo exposes security information from the S2A to the application.

func AuthInfoFromContext 

func AuthInfoFromContext(ctx context.Context) (AuthInfo, error)

AuthInfoFromContext extracts the authinfo.S2AAuthInfo object from the given context, if it exists. This API should be used by gRPC server RPC handlers to get information about the peer. On the client-side, use the grpc.Peer() CallOption and the AuthInfoFromPeer function.

func AuthInfoFromPeer 

func AuthInfoFromPeer(p *peer.Peer) (AuthInfo, error)

AuthInfoFromPeer extracts the authinfo.S2AAuthInfo object from the given peer, if it exists. This API should be used by gRPC clients after obtaining a peer object using the grpc.Peer() CallOption.

type ClientOptions 

type ClientOptions struct {
	// TargetIdentities contains a list of allowed server identities. One of the
	// target identities should match the peer identity in the handshake
	// result; otherwise, the handshake fails.
	TargetIdentities []Identity
	// LocalIdentity is the local identity of the client application. If none is
	// provided, then the S2A will choose the default identity, if one exists.
	LocalIdentity Identity
	// S2AAddress is the address of the S2A.
	S2AAddress string
	// Optional transport credentials.
	// If set, this will be used for the gRPC connection to the S2A server.
	TransportCreds credentials.TransportCredentials
	// EnsureProcessSessionTickets waits for all session tickets to be sent to
	// S2A before a process completes.
	//
	// This functionality is crucial for processes that complete very soon after
	// using S2A to establish a TLS connection, but it can be ignored for longer
	// lived processes.
	//
	// Usage example:
	//   func main() {
	//     var ensureProcessSessionTickets sync.WaitGroup
	//     clientOpts := &s2a.ClientOptions{
	//       EnsureProcessSessionTickets: &ensureProcessSessionTickets,
	//       // Set other members.
	//     }
	//     creds, _ := s2a.NewClientCreds(clientOpts)
	//     conn, _ := grpc.Dial(serverAddr, grpc.WithTransportCredentials(creds))
	//     defer conn.Close()
	//
	//     // Make RPC call.
	//
	//     // The process terminates right after the RPC call ends.
	//     // ensureProcessSessionTickets can be used to ensure resumption
	//     // tickets are fully processed. If the process is long-lived, using
	//     // ensureProcessSessionTickets is not necessary.
	//     ensureProcessSessionTickets.Wait()
	//   }
	EnsureProcessSessionTickets *sync.WaitGroup
	// If true, enables the use of legacy S2Av1.
	EnableLegacyMode bool
	// VerificationMode specifies the mode that S2A must use to verify the
	// peer certificate chain.
	VerificationMode VerificationModeType

	// Optional fallback after dialing with S2A fails.
	FallbackOpts *FallbackOptions
	// contains filtered or unexported fields
}

ClientOptions contains the client-side options used to establish a secure channel using the S2A handshaker service.

func DefaultClientOptions 

func DefaultClientOptions(s2aAddress string) *ClientOptions

DefaultClientOptions returns the default client options.

type FallbackDialer 

type FallbackDialer struct {
	// Dialer specifies a fallback tls.Dialer.
	Dialer *tls.Dialer
	// ServerAddr is used by Dialer to establish fallback connection.
	ServerAddr string
}

FallbackDialer contains a fallback tls.Dialer and a server address to connect to.

type FallbackOptions 

type FallbackOptions struct {
	// FallbackClientHandshakeFunc is used to specify fallback behavior when calling s2a.NewClientCreds().
	// It will be called by ClientHandshake function, after handshake with S2A fails.
	// s2a.NewClientCreds() ignores the other FallbackDialer field.
	FallbackClientHandshakeFunc fallback.ClientHandshake

	// FallbackDialer is used to specify fallback behavior when calling s2a.NewS2aDialTLSContextFunc().
	// It passes in a custom fallback dialer and server address to use after dialing with S2A fails.
	// s2a.NewS2aDialTLSContextFunc() ignores the other FallbackClientHandshakeFunc field.
	FallbackDialer *FallbackDialer
}

FallbackOptions prescribes the fallback logic that should be taken if the application fails to connect with S2A.

type Identity 

type Identity interface {
	// Name returns the name of the identity.
	Name() string
}

Identity is the interface for S2A identities.

func NewHostname 

func NewHostname(name string) Identity

NewHostname creates a hostname from name.

func NewSpiffeID 

func NewSpiffeID(id string) Identity

NewSpiffeID creates a SPIFFE ID from id.

func NewUID 

func NewUID(name string) Identity

NewUID creates a UID from name.

type ServerOptions 

type ServerOptions struct {
	// LocalIdentities is the list of local identities that may be assumed by
	// the server. If no local identity is specified, then the S2A chooses a
	// default local identity, if one exists.
	LocalIdentities []Identity
	// S2AAddress is the address of the S2A.
	S2AAddress string
	// Optional transport credentials.
	// If set, this will be used for the gRPC connection to the S2A server.
	TransportCreds credentials.TransportCredentials
	// If true, enables the use of legacy S2Av1.
	EnableLegacyMode bool
	// VerificationMode specifies the mode that S2A must use to verify the
	// peer certificate chain.
	VerificationMode VerificationModeType
	// contains filtered or unexported fields
}

ServerOptions contains the server-side options used to establish a secure channel using the S2A handshaker service.

func DefaultServerOptions 

func DefaultServerOptions(s2aAddress string) *ServerOptions

DefaultServerOptions returns the default server options.

type TLSClientConfigFactory 

type TLSClientConfigFactory interface {
	Build(ctx context.Context, opts *TLSClientConfigOptions) (*tls.Config, error)
}

TLSClientConfigFactory defines the interface for a client TLS config factory.

func NewTLSClientConfigFactory 

func NewTLSClientConfigFactory(opts *ClientOptions) (TLSClientConfigFactory, error)

NewTLSClientConfigFactory returns an instance of s2aTLSClientConfigFactory.

type TLSClientConfigOptions 

type TLSClientConfigOptions struct {
	// ServerName is required by s2a as the expected name when verifying the hostname found in server's certificate.
	// 		tlsConfig, _ := factory.Build(ctx, &s2a.TLSClientConfigOptions{
	//			ServerName: "example.com",
	//		})
	ServerName string
}

TLSClientConfigOptions specifies parameters for creating client TLS config.

type VerificationModeType 

type VerificationModeType int

VerificationModeType specifies the mode that S2A must use to verify the peer certificate chain.

Source Files

View all Source files

Directories

Path Synopsis
example
client
Package main establishes a connection with an Echo service.
 Package main establishes a connection with an Echo service.
echo
Package echo contains the libraries for running an Echo server.
 Package echo contains the libraries for running an Echo server.
proto/echo_go_proto
server
Package main runs an Echo service.
 Package main runs an Echo service.
Package fallback provides default implementations of fallback options when S2A fails.
 Package fallback provides default implementations of fallback options when S2A fails.
internal
authinfo
Package authinfo provides authentication and authorization information that results from the TLS handshake.
 Package authinfo provides authentication and authorization information that results from the TLS handshake.
fakehandshaker/service
Package service is a fake S2A handshaker service.
 Package service is a fake S2A handshaker service.
handshaker
Package handshaker communicates with the S2A handshaker service.
 Package handshaker communicates with the S2A handshaker service.
handshaker/service
Package service is a utility for calling the S2A handshaker service.
 Package service is a utility for calling the S2A handshaker service.
proto/common_go_proto
proto/examples/helloworld_go_proto
proto/s2a_context_go_proto
proto/s2a_go_proto
proto/v2/common_go_proto
proto/v2/s2a_context_go_proto
proto/v2/s2a_go_proto
record
Package record implements the TLS 1.3 record protocol used by the S2A transport credentials.
 Package record implements the TLS 1.3 record protocol used by the S2A transport credentials.
record/internal/aeadcrypter
Package aeadcrypter provides the interface for AEAD cipher implementations used by S2A's record protocol.
 Package aeadcrypter provides the interface for AEAD cipher implementations used by S2A's record protocol.
record/internal/aeadcrypter/testutil
Package testutil is a collection of test utilities for the AEAD crypter.
 Package testutil is a collection of test utilities for the AEAD crypter.
record/internal/halfconn
Package halfconn manages the inbound or outbound traffic of a TLS 1.3 connection.
 Package halfconn manages the inbound or outbound traffic of a TLS 1.3 connection.
tokenmanager
Package tokenmanager provides tokens for authenticating to S2A.
 Package tokenmanager provides tokens for authenticating to S2A.
v2
Package v2 provides the S2Av2 transport credentials used by a gRPC application.
 Package v2 provides the S2Av2 transport credentials used by a gRPC application.
v2/certverifier
Package certverifier offloads verifications to S2Av2.
 Package certverifier offloads verifications to S2Av2.
v2/fakes2av2
Package fakes2av2 is a fake S2Av2 Go implementation.
 Package fakes2av2 is a fake S2Av2 Go implementation.
v2/fakes2av2_server
Package main runs an S2Av2 service.
 Package main runs an S2Av2 service.
v2/remotesigner
Package remotesigner offloads private key operations to S2Av2.
 Package remotesigner offloads private key operations to S2Av2.
v2/tlsconfigstore
Package tlsconfigstore offloads operations to S2Av2.
 Package tlsconfigstore offloads operations to S2Av2.
Package retry provides a retry helper for talking to S2A gRPC server.
 Package retry provides a retry helper for talking to S2A gRPC server.
Package stream provides an interface for bidirectional streaming to the S2A server.
 Package stream provides an interface for bidirectional streaming to the S2A server.

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.