Three types of verification modes.
const (
Unspecified = iota
ConnectToGoogle
Spiffe
)
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(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(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.
AuthInfo exposes security information from the S2A to the application.
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
}
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(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.
ClientOptions contains the client-side options used to establish a secure channel using the S2A handshaker service.
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
}
func DefaultClientOptions(s2aAddress string) *ClientOptions
DefaultClientOptions returns the default client options.
FallbackDialer contains a fallback tls.Dialer and a server address to connect to.
type FallbackDialer struct {
// Dialer specifies a fallback tls.Dialer.
Dialer *tls.Dialer
// ServerAddr is used by Dialer to establish fallback connection.
ServerAddr string
}
FallbackOptions prescribes the fallback logic that should be taken if the application fails to connect with S2A.
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
}
Identity is the interface for S2A identities.
type Identity interface {
// Name returns the name of the identity.
Name() string
}
func NewHostname(name string) Identity
NewHostname creates a hostname from name.
func NewSpiffeID(id string) Identity
NewSpiffeID creates a SPIFFE ID from id.
func NewUID(name string) Identity
NewUID creates a UID from name.
ServerOptions contains the server-side options used to establish a secure channel using the S2A handshaker service.
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
}
func DefaultServerOptions(s2aAddress string) *ServerOptions
DefaultServerOptions returns the default server options.
TLSClientConfigFactory defines the interface for a client TLS config factory.
type TLSClientConfigFactory interface {
Build(ctx context.Context, opts *TLSClientConfigOptions) (*tls.Config, error)
}
func NewTLSClientConfigFactory(opts *ClientOptions) (TLSClientConfigFactory, error)
NewTLSClientConfigFactory returns an instance of s2aTLSClientConfigFactory.
TLSClientConfigOptions specifies parameters for creating client TLS config.
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
}
VerificationModeType specifies the mode that S2A must use to verify the peer certificate chain.
type VerificationModeType int
| Name | Synopsis |
|---|---|
| .. | |
| example | |
| client | Package main establishes a connection with an Echo service. |
| echo | Package echo contains the libraries for running an Echo server. |
| proto | |
| echo_go_proto | |
| server | Package main runs an Echo service. |
| fallback | Package fallback provides default implementations of fallback options when S2A fails. |
| retry | Package retry provides a retry helper for talking to S2A gRPC server. |
| stream | Package stream provides an interface for bidirectional streaming to the S2A server. |