handshaker.go

Documentation: github.com/google/s2a-go/internal/handshaker

     1  /*
     2   *
     3   * Copyright 2021 Google LLC
     4   *
     5   * Licensed under the Apache License, Version 2.0 (the "License");
     6   * you may not use this file except in compliance with the License.
     7   * You may obtain a copy of the License at
     8   *
     9   *     https://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   *
    17   */
    18  
    19  // Package handshaker communicates with the S2A handshaker service.
    20  package handshaker
    21  
    22  import (
    23  	"context"
    24  	"errors"
    25  	"fmt"
    26  	"io"
    27  	"net"
    28  	"sync"
    29  
    30  	"github.com/google/s2a-go/internal/authinfo"
    31  	commonpb "github.com/google/s2a-go/internal/proto/common_go_proto"
    32  	s2apb "github.com/google/s2a-go/internal/proto/s2a_go_proto"
    33  	"github.com/google/s2a-go/internal/record"
    34  	"github.com/google/s2a-go/internal/tokenmanager"
    35  	grpc "google.golang.org/grpc"
    36  	"google.golang.org/grpc/codes"
    37  	"google.golang.org/grpc/credentials"
    38  	"google.golang.org/grpc/grpclog"
    39  )
    40  
    41  var (
    42  	// appProtocol contains the application protocol accepted by the handshaker.
    43  	appProtocol = "grpc"
    44  	// frameLimit is the maximum size of a frame in bytes.
    45  	frameLimit = 1024 * 64
    46  	// peerNotRespondingError is the error thrown when the peer doesn't respond.
    47  	errPeerNotResponding = errors.New("peer is not responding and re-connection should be attempted")
    48  )
    49  
    50  // Handshaker defines a handshaker interface.
    51  type Handshaker interface {
    52  	// ClientHandshake starts and completes a TLS handshake from the client side,
    53  	// and returns a secure connection along with additional auth information.
    54  	ClientHandshake(ctx context.Context) (net.Conn, credentials.AuthInfo, error)
    55  	// ServerHandshake starts and completes a TLS handshake from the server side,
    56  	// and returns a secure connection along with additional auth information.
    57  	ServerHandshake(ctx context.Context) (net.Conn, credentials.AuthInfo, error)
    58  	// Close terminates the Handshaker. It should be called when the handshake
    59  	// is complete.
    60  	Close() error
    61  }
    62  
    63  // ClientHandshakerOptions contains the options needed to configure the S2A
    64  // handshaker service on the client-side.
    65  type ClientHandshakerOptions struct {
    66  	// MinTLSVersion specifies the min TLS version supported by the client.
    67  	MinTLSVersion commonpb.TLSVersion
    68  	// MaxTLSVersion specifies the max TLS version supported by the client.
    69  	MaxTLSVersion commonpb.TLSVersion
    70  	// TLSCiphersuites is the ordered list of ciphersuites supported by the
    71  	// client.
    72  	TLSCiphersuites []commonpb.Ciphersuite
    73  	// TargetIdentities contains a list of allowed server identities. One of the
    74  	// target identities should match the peer identity in the handshake
    75  	// result; otherwise, the handshake fails.
    76  	TargetIdentities []*commonpb.Identity
    77  	// LocalIdentity is the local identity of the client application. If none is
    78  	// provided, then the S2A will choose the default identity.
    79  	LocalIdentity *commonpb.Identity
    80  	// TargetName is the allowed server name, which may be used for server
    81  	// authorization check by the S2A if it is provided.
    82  	TargetName string
    83  	// EnsureProcessSessionTickets allows users to wait and ensure that all
    84  	// available session tickets are sent to S2A before a process completes.
    85  	EnsureProcessSessionTickets *sync.WaitGroup
    86  }
    87  
    88  // ServerHandshakerOptions contains the options needed to configure the S2A
    89  // handshaker service on the server-side.
    90  type ServerHandshakerOptions struct {
    91  	// MinTLSVersion specifies the min TLS version supported by the server.
    92  	MinTLSVersion commonpb.TLSVersion
    93  	// MaxTLSVersion specifies the max TLS version supported by the server.
    94  	MaxTLSVersion commonpb.TLSVersion
    95  	// TLSCiphersuites is the ordered list of ciphersuites supported by the
    96  	// server.
    97  	TLSCiphersuites []commonpb.Ciphersuite
    98  	// LocalIdentities is the list of local identities that may be assumed by
    99  	// the server. If no local identity is specified, then the S2A chooses a
   100  	// default local identity.
   101  	LocalIdentities []*commonpb.Identity
   102  }
   103  
   104  // s2aHandshaker performs a TLS handshake using the S2A handshaker service.
   105  type s2aHandshaker struct {
   106  	// stream is used to communicate with the S2A handshaker service.
   107  	stream s2apb.S2AService_SetUpSessionClient
   108  	// conn is the connection to the peer.
   109  	conn net.Conn
   110  	// clientOpts should be non-nil iff the handshaker is client-side.
   111  	clientOpts *ClientHandshakerOptions
   112  	// serverOpts should be non-nil iff the handshaker is server-side.
   113  	serverOpts *ServerHandshakerOptions
   114  	// isClient determines if the handshaker is client or server side.
   115  	isClient bool
   116  	// hsAddr stores the address of the S2A handshaker service.
   117  	hsAddr string
   118  	// tokenManager manages access tokens for authenticating to S2A.
   119  	tokenManager tokenmanager.AccessTokenManager
   120  	// localIdentities is the set of local identities for whom the
   121  	// tokenManager should fetch a token when preparing a request to be
   122  	// sent to S2A.
   123  	localIdentities []*commonpb.Identity
   124  }
   125  
   126  // NewClientHandshaker creates an s2aHandshaker instance that performs a
   127  // client-side TLS handshake using the S2A handshaker service.
   128  func NewClientHandshaker(ctx context.Context, conn *grpc.ClientConn, c net.Conn, hsAddr string, opts *ClientHandshakerOptions) (Handshaker, error) {
   129  	stream, err := s2apb.NewS2AServiceClient(conn).SetUpSession(ctx, grpc.WaitForReady(true))
   130  	if err != nil {
   131  		return nil, err
   132  	}
   133  	tokenManager, err := tokenmanager.NewSingleTokenAccessTokenManager()
   134  	if err != nil {
   135  		grpclog.Infof("failed to create single token access token manager: %v", err)
   136  	}
   137  	return newClientHandshaker(stream, c, hsAddr, opts, tokenManager), nil
   138  }
   139  
   140  func newClientHandshaker(stream s2apb.S2AService_SetUpSessionClient, c net.Conn, hsAddr string, opts *ClientHandshakerOptions, tokenManager tokenmanager.AccessTokenManager) *s2aHandshaker {
   141  	var localIdentities []*commonpb.Identity
   142  	if opts != nil {
   143  		localIdentities = []*commonpb.Identity{opts.LocalIdentity}
   144  	}
   145  	return &s2aHandshaker{
   146  		stream:          stream,
   147  		conn:            c,
   148  		clientOpts:      opts,
   149  		isClient:        true,
   150  		hsAddr:          hsAddr,
   151  		tokenManager:    tokenManager,
   152  		localIdentities: localIdentities,
   153  	}
   154  }
   155  
   156  // NewServerHandshaker creates an s2aHandshaker instance that performs a
   157  // server-side TLS handshake using the S2A handshaker service.
   158  func NewServerHandshaker(ctx context.Context, conn *grpc.ClientConn, c net.Conn, hsAddr string, opts *ServerHandshakerOptions) (Handshaker, error) {
   159  	stream, err := s2apb.NewS2AServiceClient(conn).SetUpSession(ctx, grpc.WaitForReady(true))
   160  	if err != nil {
   161  		return nil, err
   162  	}
   163  	tokenManager, err := tokenmanager.NewSingleTokenAccessTokenManager()
   164  	if err != nil {
   165  		grpclog.Infof("failed to create single token access token manager: %v", err)
   166  	}
   167  	return newServerHandshaker(stream, c, hsAddr, opts, tokenManager), nil
   168  }
   169  
   170  func newServerHandshaker(stream s2apb.S2AService_SetUpSessionClient, c net.Conn, hsAddr string, opts *ServerHandshakerOptions, tokenManager tokenmanager.AccessTokenManager) *s2aHandshaker {
   171  	var localIdentities []*commonpb.Identity
   172  	if opts != nil {
   173  		localIdentities = opts.LocalIdentities
   174  	}
   175  	return &s2aHandshaker{
   176  		stream:          stream,
   177  		conn:            c,
   178  		serverOpts:      opts,
   179  		isClient:        false,
   180  		hsAddr:          hsAddr,
   181  		tokenManager:    tokenManager,
   182  		localIdentities: localIdentities,
   183  	}
   184  }
   185  
   186  // ClientHandshake performs a client-side TLS handshake using the S2A handshaker
   187  // service. When complete, returns a TLS connection.
   188  func (h *s2aHandshaker) ClientHandshake(_ context.Context) (net.Conn, credentials.AuthInfo, error) {
   189  	if !h.isClient {
   190  		return nil, nil, errors.New("only handshakers created using NewClientHandshaker can perform a client-side handshake")
   191  	}
   192  	// Extract the hostname from the target name. The target name is assumed to be an authority.
   193  	hostname, _, err := net.SplitHostPort(h.clientOpts.TargetName)
   194  	if err != nil {
   195  		// If the target name had no host port or could not be parsed, use it as is.
   196  		hostname = h.clientOpts.TargetName
   197  	}
   198  
   199  	// Prepare a client start message to send to the S2A handshaker service.
   200  	req := &s2apb.SessionReq{
   201  		ReqOneof: &s2apb.SessionReq_ClientStart{
   202  			ClientStart: &s2apb.ClientSessionStartReq{
   203  				ApplicationProtocols: []string{appProtocol},
   204  				MinTlsVersion:        h.clientOpts.MinTLSVersion,
   205  				MaxTlsVersion:        h.clientOpts.MaxTLSVersion,
   206  				TlsCiphersuites:      h.clientOpts.TLSCiphersuites,
   207  				TargetIdentities:     h.clientOpts.TargetIdentities,
   208  				LocalIdentity:        h.clientOpts.LocalIdentity,
   209  				TargetName:           hostname,
   210  			},
   211  		},
   212  		AuthMechanisms: h.getAuthMechanisms(),
   213  	}
   214  	conn, result, err := h.setUpSession(req)
   215  	if err != nil {
   216  		return nil, nil, err
   217  	}
   218  	authInfo, err := authinfo.NewS2AAuthInfo(result)
   219  	if err != nil {
   220  		return nil, nil, err
   221  	}
   222  	return conn, authInfo, nil
   223  }
   224  
   225  // ServerHandshake performs a server-side TLS handshake using the S2A handshaker
   226  // service. When complete, returns a TLS connection.
   227  func (h *s2aHandshaker) ServerHandshake(_ context.Context) (net.Conn, credentials.AuthInfo, error) {
   228  	if h.isClient {
   229  		return nil, nil, errors.New("only handshakers created using NewServerHandshaker can perform a server-side handshake")
   230  	}
   231  	p := make([]byte, frameLimit)
   232  	n, err := h.conn.Read(p)
   233  	if err != nil {
   234  		return nil, nil, err
   235  	}
   236  	// Prepare a server start message to send to the S2A handshaker service.
   237  	req := &s2apb.SessionReq{
   238  		ReqOneof: &s2apb.SessionReq_ServerStart{
   239  			ServerStart: &s2apb.ServerSessionStartReq{
   240  				ApplicationProtocols: []string{appProtocol},
   241  				MinTlsVersion:        h.serverOpts.MinTLSVersion,
   242  				MaxTlsVersion:        h.serverOpts.MaxTLSVersion,
   243  				TlsCiphersuites:      h.serverOpts.TLSCiphersuites,
   244  				LocalIdentities:      h.serverOpts.LocalIdentities,
   245  				InBytes:              p[:n],
   246  			},
   247  		},
   248  		AuthMechanisms: h.getAuthMechanisms(),
   249  	}
   250  	conn, result, err := h.setUpSession(req)
   251  	if err != nil {
   252  		return nil, nil, err
   253  	}
   254  	authInfo, err := authinfo.NewS2AAuthInfo(result)
   255  	if err != nil {
   256  		return nil, nil, err
   257  	}
   258  	return conn, authInfo, nil
   259  }
   260  
   261  // setUpSession proxies messages between the peer and the S2A handshaker
   262  // service.
   263  func (h *s2aHandshaker) setUpSession(req *s2apb.SessionReq) (net.Conn, *s2apb.SessionResult, error) {
   264  	resp, err := h.accessHandshakerService(req)
   265  	if err != nil {
   266  		return nil, nil, err
   267  	}
   268  	// Check if the returned status is an error.
   269  	if resp.GetStatus() != nil {
   270  		if got, want := resp.GetStatus().Code, uint32(codes.OK); got != want {
   271  			return nil, nil, fmt.Errorf("%v", resp.GetStatus().Details)
   272  		}
   273  	}
   274  	// Calculate the extra unread bytes from the Session. Attempting to consume
   275  	// more than the bytes sent will throw an error.
   276  	var extra []byte
   277  	if req.GetServerStart() != nil {
   278  		if resp.GetBytesConsumed() > uint32(len(req.GetServerStart().GetInBytes())) {
   279  			return nil, nil, errors.New("handshaker service consumed bytes value is out-of-bounds")
   280  		}
   281  		extra = req.GetServerStart().GetInBytes()[resp.GetBytesConsumed():]
   282  	}
   283  	result, extra, err := h.processUntilDone(resp, extra)
   284  	if err != nil {
   285  		return nil, nil, err
   286  	}
   287  	if result.GetLocalIdentity() == nil {
   288  		return nil, nil, errors.New("local identity must be populated in session result")
   289  	}
   290  
   291  	// Create a new TLS record protocol using the Session Result.
   292  	newConn, err := record.NewConn(&record.ConnParameters{
   293  		NetConn:                     h.conn,
   294  		Ciphersuite:                 result.GetState().GetTlsCiphersuite(),
   295  		TLSVersion:                  result.GetState().GetTlsVersion(),
   296  		InTrafficSecret:             result.GetState().GetInKey(),
   297  		OutTrafficSecret:            result.GetState().GetOutKey(),
   298  		UnusedBuf:                   extra,
   299  		InSequence:                  result.GetState().GetInSequence(),
   300  		OutSequence:                 result.GetState().GetOutSequence(),
   301  		HSAddr:                      h.hsAddr,
   302  		ConnectionID:                result.GetState().GetConnectionId(),
   303  		LocalIdentity:               result.GetLocalIdentity(),
   304  		EnsureProcessSessionTickets: h.ensureProcessSessionTickets(),
   305  	})
   306  	if err != nil {
   307  		return nil, nil, err
   308  	}
   309  	return newConn, result, nil
   310  }
   311  
   312  func (h *s2aHandshaker) ensureProcessSessionTickets() *sync.WaitGroup {
   313  	if h.clientOpts == nil {
   314  		return nil
   315  	}
   316  	return h.clientOpts.EnsureProcessSessionTickets
   317  }
   318  
   319  // accessHandshakerService sends the session request to the S2A handshaker
   320  // service and returns the session response.
   321  func (h *s2aHandshaker) accessHandshakerService(req *s2apb.SessionReq) (*s2apb.SessionResp, error) {
   322  	if err := h.stream.Send(req); err != nil {
   323  		return nil, err
   324  	}
   325  	resp, err := h.stream.Recv()
   326  	if err != nil {
   327  		return nil, err
   328  	}
   329  	return resp, nil
   330  }
   331  
   332  // processUntilDone continues proxying messages between the peer and the S2A
   333  // handshaker service until the handshaker service returns the SessionResult at
   334  // the end of the handshake or an error occurs.
   335  func (h *s2aHandshaker) processUntilDone(resp *s2apb.SessionResp, unusedBytes []byte) (*s2apb.SessionResult, []byte, error) {
   336  	for {
   337  		if len(resp.OutFrames) > 0 {
   338  			if _, err := h.conn.Write(resp.OutFrames); err != nil {
   339  				return nil, nil, err
   340  			}
   341  		}
   342  		if resp.Result != nil {
   343  			return resp.Result, unusedBytes, nil
   344  		}
   345  		buf := make([]byte, frameLimit)
   346  		n, err := h.conn.Read(buf)
   347  		if err != nil && err != io.EOF {
   348  			return nil, nil, err
   349  		}
   350  		// If there is nothing to send to the handshaker service and nothing is
   351  		// received from the peer, then we are stuck. This covers the case when
   352  		// the peer is not responding. Note that handshaker service connection
   353  		// issues are caught in accessHandshakerService before we even get
   354  		// here.
   355  		if len(resp.OutFrames) == 0 && n == 0 {
   356  			return nil, nil, errPeerNotResponding
   357  		}
   358  		// Append extra bytes from the previous interaction with the handshaker
   359  		// service with the current buffer read from conn.
   360  		p := append(unusedBytes, buf[:n]...)
   361  		// From here on, p and unusedBytes point to the same slice.
   362  		resp, err = h.accessHandshakerService(&s2apb.SessionReq{
   363  			ReqOneof: &s2apb.SessionReq_Next{
   364  				Next: &s2apb.SessionNextReq{
   365  					InBytes: p,
   366  				},
   367  			},
   368  			AuthMechanisms: h.getAuthMechanisms(),
   369  		})
   370  		if err != nil {
   371  			return nil, nil, err
   372  		}
   373  
   374  		// Cache the local identity returned by S2A, if it is populated. This
   375  		// overwrites any existing local identities. This is done because, once the
   376  		// S2A has selected a local identity, then only that local identity should
   377  		// be asserted in future requests until the end of the current handshake.
   378  		if resp.GetLocalIdentity() != nil {
   379  			h.localIdentities = []*commonpb.Identity{resp.GetLocalIdentity()}
   380  		}
   381  
   382  		// Set unusedBytes based on the handshaker service response.
   383  		if resp.GetBytesConsumed() > uint32(len(p)) {
   384  			return nil, nil, errors.New("handshaker service consumed bytes value is out-of-bounds")
   385  		}
   386  		unusedBytes = p[resp.GetBytesConsumed():]
   387  	}
   388  }
   389  
   390  // Close shuts down the handshaker and the stream to the S2A handshaker service
   391  // when the handshake is complete. It should be called when the caller obtains
   392  // the secure connection at the end of the handshake.
   393  func (h *s2aHandshaker) Close() error {
   394  	return h.stream.CloseSend()
   395  }
   396  
   397  func (h *s2aHandshaker) getAuthMechanisms() []*s2apb.AuthenticationMechanism {
   398  	if h.tokenManager == nil {
   399  		return nil
   400  	}
   401  	// First handle the special case when no local identities have been provided
   402  	// by the application. In this case, an AuthenticationMechanism with no local
   403  	// identity will be sent.
   404  	if len(h.localIdentities) == 0 {
   405  		token, err := h.tokenManager.DefaultToken()
   406  		if err != nil {
   407  			grpclog.Infof("unable to get token for empty local identity: %v", err)
   408  			return nil
   409  		}
   410  		return []*s2apb.AuthenticationMechanism{
   411  			{
   412  				MechanismOneof: &s2apb.AuthenticationMechanism_Token{
   413  					Token: token,
   414  				},
   415  			},
   416  		}
   417  	}
   418  
   419  	// Next, handle the case where the application (or the S2A) has provided
   420  	// one or more local identities.
   421  	var authMechanisms []*s2apb.AuthenticationMechanism
   422  	for _, localIdentity := range h.localIdentities {
   423  		token, err := h.tokenManager.Token(localIdentity)
   424  		if err != nil {
   425  			grpclog.Infof("unable to get token for local identity %v: %v", localIdentity, err)
   426  			continue
   427  		}
   428  
   429  		authMechanism := &s2apb.AuthenticationMechanism{
   430  			Identity: localIdentity,
   431  			MechanismOneof: &s2apb.AuthenticationMechanism_Token{
   432  				Token: token,
   433  			},
   434  		}
   435  		authMechanisms = append(authMechanisms, authMechanism)
   436  	}
   437  	return authMechanisms
   438  }
   439
View as plain text