snapshot of https://github.com/grpc/grpc-go.git (master, 2026-09-15; blobs > 131072B omitted)

credentials/alts/internal/handshaker/handshaker.go

@@ -0,0 +1,381 @@
+/*
+ *
+ * Copyright 2018 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+// Package handshaker provides ALTS handshaking functionality for GCP.
+package handshaker
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"time"
+
+	"golang.org/x/sync/semaphore"
+	grpc "google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/credentials"
+	core "google.golang.org/grpc/credentials/alts/internal"
+	"google.golang.org/grpc/credentials/alts/internal/authinfo"
+	"google.golang.org/grpc/credentials/alts/internal/conn"
+	altsgrpc "google.golang.org/grpc/credentials/alts/internal/proto/grpc_gcp"
+	altspb "google.golang.org/grpc/credentials/alts/internal/proto/grpc_gcp"
+	"google.golang.org/grpc/internal/envconfig"
+)
+
+const (
+	// The maximum byte size of receive frames.
+	frameLimit              = 64 * 1024 // 64 KB
+	rekeyRecordProtocolName = "ALTSRP_GCM_AES128_REKEY"
+)
+
+var (
+	hsProtocol      = altspb.HandshakeProtocol_ALTS
+	appProtocols    = []string{"grpc"}
+	recordProtocols = []string{rekeyRecordProtocolName}
+	keyLength       = map[string]int{
+		rekeyRecordProtocolName: 44,
+	}
+	altsRecordFuncs = map[string]conn.ALTSRecordFunc{
+		// ALTS handshaker protocols.
+		rekeyRecordProtocolName: func(s core.Side, keyData []byte) (conn.ALTSRecordCrypto, error) {
+			return conn.NewAES128GCMRekey(s, keyData)
+		},
+	}
+	// control number of concurrent created (but not closed) handshakes.
+	clientHandshakes = semaphore.NewWeighted(int64(envconfig.ALTSMaxConcurrentHandshakes))
+	serverHandshakes = semaphore.NewWeighted(int64(envconfig.ALTSMaxConcurrentHandshakes))
+	// errOutOfBound occurs when the handshake service returns a consumed
+	// bytes value larger than the buffer that was passed to it originally.
+	errOutOfBound = errors.New("handshaker service consumed bytes value is out-of-bound")
+)
+
+func init() {
+	for protocol, f := range altsRecordFuncs {
+		if err := conn.RegisterProtocol(protocol, f); err != nil {
+			panic(err)
+		}
+	}
+}
+
+// ClientHandshakerOptions contains the client handshaker options that can
+// provided by the caller.
+type ClientHandshakerOptions struct {
+	// ClientIdentity is the handshaker client local identity.
+	ClientIdentity *altspb.Identity
+	// TargetName is the server service account name for secure name
+	// checking.
+	TargetName string
+	// TargetServiceAccounts contains a list of expected target service
+	// accounts. One of these accounts should match one of the accounts in
+	// the handshaker results. Otherwise, the handshake fails.
+	TargetServiceAccounts []string
+	// RPCVersions specifies the gRPC versions accepted by the client.
+	RPCVersions *altspb.RpcProtocolVersions
+	// BoundAccessToken is a bound access token to be sent to the server for authentication.
+	BoundAccessToken string
+}
+
+// ServerHandshakerOptions contains the server handshaker options that can
+// provided by the caller.
+type ServerHandshakerOptions struct {
+	// RPCVersions specifies the gRPC versions accepted by the server.
+	RPCVersions *altspb.RpcProtocolVersions
+}
+
+// DefaultClientHandshakerOptions returns the default client handshaker options.
+func DefaultClientHandshakerOptions() *ClientHandshakerOptions {
+	return &ClientHandshakerOptions{}
+}
+
+// DefaultServerHandshakerOptions returns the default client handshaker options.
+func DefaultServerHandshakerOptions() *ServerHandshakerOptions {
+	return &ServerHandshakerOptions{}
+}
+
+// altsHandshaker is used to complete an ALTS handshake between client and
+// server. This handshaker talks to the ALTS handshaker service in the metadata
+// server.
+type altsHandshaker struct {
+	// RPC stream used to access the ALTS Handshaker service.
+	stream altsgrpc.HandshakerService_DoHandshakeClient
+	// the connection to the peer.
+	conn net.Conn
+	// a virtual connection to the ALTS handshaker service.
+	clientConn *grpc.ClientConn
+	// client handshake options.
+	clientOpts *ClientHandshakerOptions
+	// server handshake options.
+	serverOpts *ServerHandshakerOptions
+	// defines the side doing the handshake, client or server.
+	side core.Side
+}
+
+// NewClientHandshaker creates a core.Handshaker that performs a client-side
+// ALTS handshake by acting as a proxy between the peer and the ALTS handshaker
+// service in the metadata server.
+func NewClientHandshaker(_ context.Context, conn *grpc.ClientConn, c net.Conn, opts *ClientHandshakerOptions) (core.Handshaker, error) {
+	return &altsHandshaker{
+		stream:     nil,
+		conn:       c,
+		clientConn: conn,
+		clientOpts: opts,
+		side:       core.ClientSide,
+	}, nil
+}
+
+// NewServerHandshaker creates a core.Handshaker that performs a server-side
+// ALTS handshake by acting as a proxy between the peer and the ALTS handshaker
+// service in the metadata server.
+func NewServerHandshaker(_ context.Context, conn *grpc.ClientConn, c net.Conn, opts *ServerHandshakerOptions) (core.Handshaker, error) {
+	return &altsHandshaker{
+		stream:     nil,
+		conn:       c,
+		clientConn: conn,
+		serverOpts: opts,
+		side:       core.ServerSide,
+	}, nil
+}
+
+// ClientHandshake starts and completes a client ALTS handshake for GCP. Once
+// done, ClientHandshake returns a secure connection.
+func (h *altsHandshaker) ClientHandshake(ctx context.Context) (net.Conn, credentials.AuthInfo, error) {
+	if err := clientHandshakes.Acquire(ctx, 1); err != nil {
+		return nil, nil, err
+	}
+	defer clientHandshakes.Release(1)
+
+	if h.side != core.ClientSide {
+		return nil, nil, errors.New("only handshakers created using NewClientHandshaker can perform a client handshaker")
+	}
+
+	// TODO(matthewstevenson88): Change unit tests to use public APIs so
+	// that h.stream can unconditionally be set based on h.clientConn.
+	if h.stream == nil {
+		stream, err := altsgrpc.NewHandshakerServiceClient(h.clientConn).DoHandshake(ctx)
+		if err != nil {
+			return nil, nil, fmt.Errorf("failed to establish stream to ALTS handshaker service: %v", err)
+		}
+		h.stream = stream
+	}
+
+	// Create target identities from service account list.
+	targetIdentities := make([]*altspb.Identity, 0, len(h.clientOpts.TargetServiceAccounts))
+	for _, account := range h.clientOpts.TargetServiceAccounts {
+		targetIdentities = append(targetIdentities, &altspb.Identity{
+			IdentityOneof: &altspb.Identity_ServiceAccount{
+				ServiceAccount: account,
+			},
+		})
+	}
+	req := &altspb.HandshakerReq{
+		ReqOneof: &altspb.HandshakerReq_ClientStart{
+			ClientStart: &altspb.StartClientHandshakeReq{
+				HandshakeSecurityProtocol: hsProtocol,
+				ApplicationProtocols:      appProtocols,
+				RecordProtocols:           recordProtocols,
+				TargetIdentities:          targetIdentities,
+				LocalIdentity:             h.clientOpts.ClientIdentity,
+				TargetName:                h.clientOpts.TargetName,
+				RpcVersions:               h.clientOpts.RPCVersions,
+			},
+		},
+	}
+	if h.clientOpts.BoundAccessToken != "" {
+		req.GetClientStart().AccessToken = h.clientOpts.BoundAccessToken
+	}
+	conn, result, err := h.doHandshake(req)
+	if err != nil {
+		return nil, nil, err
+	}
+	authInfo := authinfo.New(result)
+	return conn, authInfo, nil
+}
+
+// ServerHandshake starts and completes a server ALTS handshake for GCP. Once
+// done, ServerHandshake returns a secure connection.
+func (h *altsHandshaker) ServerHandshake(ctx context.Context) (net.Conn, credentials.AuthInfo, error) {
+	if err := serverHandshakes.Acquire(ctx, 1); err != nil {
+		return nil, nil, err
+	}
+	defer serverHandshakes.Release(1)
+
+	if h.side != core.ServerSide {
+		return nil, nil, errors.New("only handshakers created using NewServerHandshaker can perform a server handshaker")
+	}
+
+	// TODO(matthewstevenson88): Change unit tests to use public APIs so
+	// that h.stream can unconditionally be set based on h.clientConn.
+	if h.stream == nil {
+		stream, err := altsgrpc.NewHandshakerServiceClient(h.clientConn).DoHandshake(ctx)
+		if err != nil {
+			return nil, nil, fmt.Errorf("failed to establish stream to ALTS handshaker service: %v", err)
+		}
+		h.stream = stream
+	}
+
+	p := make([]byte, frameLimit)
+	n, err := h.conn.Read(p)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	// Prepare server parameters.
+	params := make(map[int32]*altspb.ServerHandshakeParameters)
+	params[int32(altspb.HandshakeProtocol_ALTS)] = &altspb.ServerHandshakeParameters{
+		RecordProtocols: recordProtocols,
+	}
+	req := &altspb.HandshakerReq{
+		ReqOneof: &altspb.HandshakerReq_ServerStart{
+			ServerStart: &altspb.StartServerHandshakeReq{
+				ApplicationProtocols: appProtocols,
+				HandshakeParameters:  params,
+				InBytes:              p[:n],
+				RpcVersions:          h.serverOpts.RPCVersions,
+			},
+		},
+	}
+
+	conn, result, err := h.doHandshake(req)
+	if err != nil {
+		return nil, nil, err
+	}
+	authInfo := authinfo.New(result)
+	return conn, authInfo, nil
+}
+
+func (h *altsHandshaker) doHandshake(req *altspb.HandshakerReq) (net.Conn, *altspb.HandshakerResult, error) {
+	resp, err := h.accessHandshakerService(req)
+	if err != nil {
+		return nil, nil, err
+	}
+	// Check of the returned status is an error.
+	if resp.GetStatus() != nil {
+		if got, want := resp.GetStatus().Code, uint32(codes.OK); got != want {
+			return nil, nil, fmt.Errorf("%v", resp.GetStatus().Details)
+		}
+	}
+
+	var extra []byte
+	if req.GetServerStart() != nil {
+		if resp.GetBytesConsumed() > uint32(len(req.GetServerStart().GetInBytes())) {
+			return nil, nil, errOutOfBound
+		}
+		extra = req.GetServerStart().GetInBytes()[resp.GetBytesConsumed():]
+	}
+	result, extra, err := h.processUntilDone(resp, extra)
+	if err != nil {
+		return nil, nil, err
+	}
+	// The handshaker returns a 128 bytes key. It should be truncated based
+	// on the returned record protocol.
+	keyLen, ok := keyLength[result.RecordProtocol]
+	if !ok {
+		return nil, nil, fmt.Errorf("unknown resulted record protocol %v", result.RecordProtocol)
+	}
+	maxFrameSize := int(envconfig.ALTSMaxFrameSize)
+	if peerMax := int(result.GetMaxFrameSize()); peerMax > 0 {
+		maxFrameSize = min(peerMax, maxFrameSize)
+	}
+	sc, err := conn.NewConnWithMaxFrameSize(h.conn, h.side, result.GetRecordProtocol(), result.KeyData[:keyLen], extra, maxFrameSize)
+	if err != nil {
+		return nil, nil, err
+	}
+	return sc, result, nil
+}
+
+func (h *altsHandshaker) accessHandshakerService(req *altspb.HandshakerReq) (*altspb.HandshakerResp, error) {
+	if err := h.stream.Send(req); err != nil {
+		return nil, fmt.Errorf("failed to send ALTS handshaker request: %w", err)
+	}
+	resp, err := h.stream.Recv()
+	if err != nil {
+		return nil, fmt.Errorf("failed to receive ALTS handshaker response: %w", err)
+	}
+	return resp, nil
+}
+
+// processUntilDone processes the handshake until the handshaker service returns
+// the results. Handshaker service takes care of frame parsing, so we read
+// whatever received from the network and send it to the handshaker service.
+func (h *altsHandshaker) processUntilDone(resp *altspb.HandshakerResp, extra []byte) (*altspb.HandshakerResult, []byte, error) {
+	var lastWriteTime time.Time
+	buf := make([]byte, frameLimit)
+	for {
+		if len(resp.OutFrames) > 0 {
+			lastWriteTime = time.Now()
+			if _, err := h.conn.Write(resp.OutFrames); err != nil {
+				return nil, nil, err
+			}
+		}
+		if resp.Result != nil {
+			return resp.Result, extra, nil
+		}
+		n, err := h.conn.Read(buf)
+		if err != nil && err != io.EOF {
+			return nil, nil, err
+		}
+		// If there is nothing to send to the handshaker service, and
+		// nothing is received from the peer, then we are stuck.
+		// This covers the case when the peer is not responding. Note
+		// that handshaker service connection issues are caught in
+		// accessHandshakerService before we even get here.
+		if len(resp.OutFrames) == 0 && n == 0 {
+			return nil, nil, core.PeerNotRespondingError
+		}
+		// Append extra bytes from the previous interaction with the
+		// handshaker service with the current buffer read from conn.
+		p := append(extra, buf[:n]...)
+		// Compute the time elapsed since the last write to the peer.
+		timeElapsed := time.Since(lastWriteTime)
+		timeElapsedMs := uint32(timeElapsed.Milliseconds())
+		// From here on, p and extra point to the same slice.
+		resp, err = h.accessHandshakerService(&altspb.HandshakerReq{
+			ReqOneof: &altspb.HandshakerReq_Next{
+				Next: &altspb.NextHandshakeMessageReq{
+					InBytes:          p,
+					NetworkLatencyMs: timeElapsedMs,
+				},
+			},
+		})
+		if err != nil {
+			return nil, nil, err
+		}
+		// Set extra based on handshaker service response.
+		if resp.GetBytesConsumed() > uint32(len(p)) {
+			return nil, nil, errOutOfBound
+		}
+		extra = p[resp.GetBytesConsumed():]
+	}
+}
+
+// Close terminates the Handshaker. It should be called when the caller obtains
+// the secure connection.
+func (h *altsHandshaker) Close() {
+	if h.stream != nil {
+		h.stream.CloseSend()
+	}
+}
+
+// ResetConcurrentHandshakeSemaphoreForTesting resets the handshake semaphores
+// to allow numberOfAllowedHandshakes concurrent handshakes each.
+func ResetConcurrentHandshakeSemaphoreForTesting(numberOfAllowedHandshakes int64) {
+	clientHandshakes = semaphore.NewWeighted(numberOfAllowedHandshakes)
+	serverHandshakes = semaphore.NewWeighted(numberOfAllowedHandshakes)
+}

credentials/alts/internal/handshaker/handshaker_test.go

@@ -0,0 +1,437 @@
+/*
+ *
+ * Copyright 2018 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package handshaker
+
+import (
+	"bytes"
+	"context"
+	"encoding/binary"
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
+	grpc "google.golang.org/grpc"
+	core "google.golang.org/grpc/credentials/alts/internal"
+	altspb "google.golang.org/grpc/credentials/alts/internal/proto/grpc_gcp"
+	"google.golang.org/grpc/credentials/alts/internal/testutil"
+	"google.golang.org/grpc/internal/envconfig"
+	"google.golang.org/grpc/internal/grpctest"
+)
+
+type s struct {
+	grpctest.Tester
+}
+
+func Test(t *testing.T) {
+	grpctest.RunSubTests(t, s{})
+}
+
+var (
+	testRecordProtocol = rekeyRecordProtocolName
+	testKey            = []byte{
+		// 44 arbitrary bytes.
+		0x1f, 0x8b, 0x08, 0x00, 0x00, 0x09, 0x6e, 0x88, 0x02, 0xff, 0xe2, 0xd2, 0x4c, 0xce, 0x4f, 0x49,
+		0x08, 0x00, 0x00, 0x09, 0x6e, 0x88, 0x02, 0xff, 0xe2, 0xd2, 0x4c, 0xce, 0x4f, 0x49, 0x1f, 0x8b,
+		0xd2, 0x4c, 0xce, 0x08, 0x00, 0x00, 0x09, 0x6e, 0x88, 0x02, 0xff, 0xe2,
+	}
+	testServiceAccount        = "test_service_account"
+	testTargetServiceAccounts = []string{testServiceAccount}
+	testClientIdentity        = &altspb.Identity{
+		IdentityOneof: &altspb.Identity_Hostname{
+			Hostname: "i_am_a_client",
+		},
+	}
+)
+
+const defaultTestTimeout = 10 * time.Second
+
+// testRPCStream mimics a altspb.HandshakerService_DoHandshakeClient object.
+type testRPCStream struct {
+	grpc.ClientStream
+	t        *testing.T
+	isClient bool
+	// The resp expected to be returned by Recv(). Make sure this is set to
+	// the content the test requires before Recv() is invoked.
+	recvBuf *altspb.HandshakerResp
+	// false if it is the first access to Handshaker service on Envelope.
+	first bool
+	// useful for testing concurrent calls.
+	delay time.Duration
+	// The minimum expected value of the network_latency_ms field in a
+	// NextHandshakeMessageReq.
+	minExpectedNetworkLatency time.Duration
+	// peerMaxFrameSize is the max_frame_size in the HandshakerResult.
+	peerMaxFrameSize uint32
+}
+
+func (t *testRPCStream) Recv() (*altspb.HandshakerResp, error) {
+	resp := t.recvBuf
+	t.recvBuf = nil
+	return resp, nil
+}
+
+func (t *testRPCStream) Send(req *altspb.HandshakerReq) error {
+	var resp *altspb.HandshakerResp
+	if !t.first {
+		// Generate the bytes to be returned by Recv() for the initial
+		// handshaking.
+		t.first = true
+		if t.isClient {
+			resp = &altspb.HandshakerResp{
+				OutFrames: testutil.MakeFrame("ClientInit"),
+				// Simulate consuming ServerInit.
+				BytesConsumed: 14,
+			}
+		} else {
+			resp = &altspb.HandshakerResp{
+				OutFrames: testutil.MakeFrame("ServerInit"),
+				// Simulate consuming ClientInit.
+				BytesConsumed: 14,
+			}
+		}
+	} else {
+		switch req := req.ReqOneof.(type) {
+		case *altspb.HandshakerReq_Next:
+			// Compare the network_latency_ms field to the minimum expected network
+			// latency.
+			if nl := time.Duration(req.Next.NetworkLatencyMs) * time.Millisecond; nl < t.minExpectedNetworkLatency {
+				return fmt.Errorf("networkLatency (%v) is smaller than expected min network latency (%v)", nl, t.minExpectedNetworkLatency)
+			}
+		default:
+			return fmt.Errorf("handshake request has unexpected type: %v", req)
+		}
+
+		// Add delay to test concurrent calls.
+		cleanup := stat.Update()
+		defer cleanup()
+		time.Sleep(t.delay)
+
+		// Generate the response to be returned by Recv() for the
+		// follow-up handshaking.
+		result := &altspb.HandshakerResult{
+			RecordProtocol: testRecordProtocol,
+			KeyData:        testKey,
+			MaxFrameSize:   t.peerMaxFrameSize,
+		}
+		resp = &altspb.HandshakerResp{
+			Result: result,
+			// Simulate consuming ClientFinished or ServerFinished.
+			BytesConsumed: 18,
+		}
+	}
+	t.recvBuf = resp
+	return nil
+}
+
+func (t *testRPCStream) CloseSend() error {
+	return nil
+}
+
+var stat testutil.Stats
+
+func (s) TestClientHandshake(t *testing.T) {
+	for _, testCase := range []struct {
+		delay              time.Duration
+		numberOfHandshakes int
+		readLatency        time.Duration
+	}{
+		{0 * time.Millisecond, 1, time.Duration(0)},
+		{0 * time.Millisecond, 1, 2 * time.Millisecond},
+		{100 * time.Millisecond, 10 * int(envconfig.ALTSMaxConcurrentHandshakes), time.Duration(0)},
+	} {
+		errc := make(chan error)
+		stat.Reset()
+
+		ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+		defer cancel()
+
+		for i := 0; i < testCase.numberOfHandshakes; i++ {
+			stream := &testRPCStream{
+				t:                         t,
+				isClient:                  true,
+				minExpectedNetworkLatency: testCase.readLatency,
+			}
+			// Preload the inbound frames.
+			f1 := testutil.MakeFrame("ServerInit")
+			f2 := testutil.MakeFrame("ServerFinished")
+			in := bytes.NewBuffer(f1)
+			in.Write(f2)
+			out := new(bytes.Buffer)
+			tc := testutil.NewTestConnWithReadLatency(in, out, testCase.readLatency)
+			chs := &altsHandshaker{
+				stream: stream,
+				conn:   tc,
+				clientOpts: &ClientHandshakerOptions{
+					TargetServiceAccounts: testTargetServiceAccounts,
+					ClientIdentity:        testClientIdentity,
+				},
+				side: core.ClientSide,
+			}
+			go func() {
+				_, context, err := chs.ClientHandshake(ctx)
+				if err == nil && context == nil {
+					errc <- errors.New("expected non-nil ALTS context")
+					return
+				}
+				errc <- err
+				chs.Close()
+			}()
+		}
+
+		// Ensure that there are no errors.
+		for i := 0; i < testCase.numberOfHandshakes; i++ {
+			if err := <-errc; err != nil {
+				t.Errorf("ClientHandshake() = _, %v, want _, <nil>", err)
+			}
+		}
+
+		// Ensure that there are no concurrent calls more than the limit.
+		if stat.MaxConcurrentCalls > int(envconfig.ALTSMaxConcurrentHandshakes) {
+			t.Errorf("Observed %d concurrent handshakes; want <= %d", stat.MaxConcurrentCalls, envconfig.ALTSMaxConcurrentHandshakes)
+		}
+	}
+}
+
+func (s) TestServerHandshake(t *testing.T) {
+	for _, testCase := range []struct {
+		delay              time.Duration
+		numberOfHandshakes int
+	}{
+		{0 * time.Millisecond, 1},
+		{100 * time.Millisecond, 10 * int(envconfig.ALTSMaxConcurrentHandshakes)},
+	} {
+		errc := make(chan error)
+		stat.Reset()
+
+		ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+		defer cancel()
+
+		for i := 0; i < testCase.numberOfHandshakes; i++ {
+			stream := &testRPCStream{
+				t:        t,
+				isClient: false,
+			}
+			// Preload the inbound frames.
+			f1 := testutil.MakeFrame("ClientInit")
+			f2 := testutil.MakeFrame("ClientFinished")
+			in := bytes.NewBuffer(f1)
+			in.Write(f2)
+			out := new(bytes.Buffer)
+			tc := testutil.NewTestConn(in, out)
+			shs := &altsHandshaker{
+				stream:     stream,
+				conn:       tc,
+				serverOpts: DefaultServerHandshakerOptions(),
+				side:       core.ServerSide,
+			}
+			go func() {
+				_, context, err := shs.ServerHandshake(ctx)
+				if err == nil && context == nil {
+					errc <- errors.New("expected non-nil ALTS context")
+					return
+				}
+				errc <- err
+				shs.Close()
+			}()
+		}
+
+		// Ensure that there are no errors.
+		for i := 0; i < testCase.numberOfHandshakes; i++ {
+			if err := <-errc; err != nil {
+				t.Errorf("ServerHandshake() = _, %v, want _, <nil>", err)
+			}
+		}
+
+		// Ensure that there are no concurrent calls more than the limit.
+		if stat.MaxConcurrentCalls > int(envconfig.ALTSMaxConcurrentHandshakes) {
+			t.Errorf("Observed %d concurrent handshakes; want <= %d", stat.MaxConcurrentCalls, envconfig.ALTSMaxConcurrentHandshakes)
+		}
+	}
+}
+
+// testUnresponsiveRPCStream is used for testing the PeerNotResponding case.
+type testUnresponsiveRPCStream struct {
+	grpc.ClientStream
+}
+
+func (t *testUnresponsiveRPCStream) Recv() (*altspb.HandshakerResp, error) {
+	return &altspb.HandshakerResp{}, nil
+}
+
+func (t *testUnresponsiveRPCStream) Send(*altspb.HandshakerReq) error {
+	return nil
+}
+
+func (t *testUnresponsiveRPCStream) CloseSend() error {
+	return nil
+}
+
+func (s) TestPeerNotResponding(t *testing.T) {
+	stream := &testUnresponsiveRPCStream{}
+	chs := &altsHandshaker{
+		stream: stream,
+		conn:   testutil.NewUnresponsiveTestConn(),
+		clientOpts: &ClientHandshakerOptions{
+			TargetServiceAccounts: testTargetServiceAccounts,
+			ClientIdentity:        testClientIdentity,
+		},
+		side: core.ClientSide,
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	_, context, err := chs.ClientHandshake(ctx)
+	chs.Close()
+	if context != nil {
+		t.Error("expected non-nil ALTS context")
+	}
+	if got, want := err, core.PeerNotRespondingError; got != want {
+		t.Errorf("ClientHandshake() = %v, want %v", got, want)
+	}
+}
+
+func (s) TestNewClientHandshaker(t *testing.T) {
+	conn := testutil.NewTestConn(nil, nil)
+	clientConn := &grpc.ClientConn{}
+	opts := &ClientHandshakerOptions{}
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	hs, err := NewClientHandshaker(ctx, clientConn, conn, opts)
+	if err != nil {
+		t.Errorf("NewClientHandshaker returned unexpected error: %v", err)
+	}
+	expectedHs := &altsHandshaker{
+		stream:     nil,
+		conn:       conn,
+		clientConn: clientConn,
+		clientOpts: opts,
+		serverOpts: nil,
+		side:       core.ClientSide,
+	}
+	cmpOpts := []cmp.Option{
+		cmp.AllowUnexported(altsHandshaker{}),
+		cmpopts.IgnoreFields(altsHandshaker{}, "conn", "clientConn"),
+	}
+	if got, want := hs.(*altsHandshaker), expectedHs; !cmp.Equal(got, want, cmpOpts...) {
+		t.Errorf("NewClientHandshaker() returned unexpected handshaker: got: %v, want: %v", got, want)
+	}
+	if hs.(*altsHandshaker).stream != nil {
+		t.Errorf("NewClientHandshaker() returned handshaker with non-nil stream")
+	}
+	if hs.(*altsHandshaker).clientConn != clientConn {
+		t.Errorf("NewClientHandshaker() returned handshaker with unexpected clientConn")
+	}
+	hs.Close()
+}
+
+func (s) TestNewServerHandshaker(t *testing.T) {
+	conn := testutil.NewTestConn(nil, nil)
+	clientConn := &grpc.ClientConn{}
+	opts := &ServerHandshakerOptions{}
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	hs, err := NewServerHandshaker(ctx, clientConn, conn, opts)
+	if err != nil {
+		t.Errorf("NewServerHandshaker returned unexpected error: %v", err)
+	}
+	expectedHs := &altsHandshaker{
+		stream:     nil,
+		conn:       conn,
+		clientConn: clientConn,
+		clientOpts: nil,
+		serverOpts: opts,
+		side:       core.ServerSide,
+	}
+	cmpOpts := []cmp.Option{
+		cmp.AllowUnexported(altsHandshaker{}),
+		cmpopts.IgnoreFields(altsHandshaker{}, "conn", "clientConn"),
+	}
+	if got, want := hs.(*altsHandshaker), expectedHs; !cmp.Equal(got, want, cmpOpts...) {
+		t.Errorf("NewServerHandshaker() returned unexpected handshaker: got: %v, want: %v", got, want)
+	}
+	if hs.(*altsHandshaker).stream != nil {
+		t.Errorf("NewServerHandshaker() returned handshaker with non-nil stream")
+	}
+	if hs.(*altsHandshaker).clientConn != clientConn {
+		t.Errorf("NewServerHandshaker() returned handshaker with unexpected clientConn")
+	}
+	hs.Close()
+}
+
+func (s) TestHandshakeMaxFrameSizeNegotiation(t *testing.T) {
+	old := envconfig.ALTSMaxFrameSize
+	envconfig.ALTSMaxFrameSize = 64 * 1024
+	defer func() { envconfig.ALTSMaxFrameSize = old }()
+
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+
+	stream := &testRPCStream{
+		t:                t,
+		isClient:         true,
+		peerMaxFrameSize: 1024 * 1024,
+	}
+	f1 := testutil.MakeFrame("ServerInit")
+	f2 := testutil.MakeFrame("ServerFinished")
+	in := bytes.NewBuffer(f1)
+	in.Write(f2)
+	out := new(bytes.Buffer)
+	tc := testutil.NewTestConn(in, out)
+	chs := &altsHandshaker{
+		stream: stream,
+		conn:   tc,
+		clientOpts: &ClientHandshakerOptions{
+			TargetServiceAccounts: testTargetServiceAccounts,
+			ClientIdentity:        testClientIdentity,
+		},
+		side: core.ClientSide,
+	}
+	defer chs.Close()
+
+	sc, _, err := chs.ClientHandshake(ctx)
+	if err != nil {
+		t.Fatalf("ClientHandshake() failed: %v", err)
+	}
+	if sc == nil {
+		t.Fatal("ClientHandshake() returned nil conn, want non-nil")
+	}
+
+	// Clear any handshake frames written to out during ClientHandshake.
+	out.Reset()
+
+	// Write a payload large enough to produce a full ALTS frame.
+	payload := make([]byte, 128*1024)
+	if _, err := sc.Write(payload); err != nil {
+		t.Fatalf("Secure conn Write() failed: %v", err)
+	}
+	// In ALTS wire format, the first 4 bytes of a frame contain the little-endian
+	// frame length (frameLen). Writing a large payload splits it into frames of
+	// the maximum calculated size. We verify the connection's max frame size by
+	// asserting that the total wire frame length (4 + frameLen) equals 64 * 1024.
+	if len(out.Bytes()) < 4 {
+		t.Fatalf("Output buffer too small: %d bytes", len(out.Bytes()))
+	}
+	frameLen := int(binary.LittleEndian.Uint32(out.Bytes()[:4]))
+	if got, want := 4+frameLen, 64*1024; got != want {
+		t.Errorf("Wire frame size = %v, want %v", got, want)
+	}
+}

credentials/alts/internal/handshaker/service/service.go

@@ -0,0 +1,91 @@
+/*
+ *
+ * Copyright 2018 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+// Package service manages connections between the VM application and the ALTS
+// handshaker service.
+package service
+
+import (
+	"sync"
+	"time"
+
+	grpc "google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+	"google.golang.org/grpc/internal/envconfig"
+	"google.golang.org/grpc/keepalive"
+)
+
+var (
+	// mu guards hsConnMap and hsDialer.
+	mu sync.Mutex
+	// hsConn represents a mapping from a hypervisor handshaker service address
+	// to a corresponding connection to a hypervisor handshaker service
+	// instance.
+	hsConnMap = make(map[string]*grpc.ClientConn)
+)
+
+// Dial dials the handshake service in the hypervisor. If a connection has
+// already been established, this function returns it. Otherwise, a new
+// connection is created.
+func Dial(hsAddress string) (*grpc.ClientConn, error) {
+	mu.Lock()
+	defer mu.Unlock()
+
+	hsConn, ok := hsConnMap[hsAddress]
+	if !ok {
+		// Create a new connection to the handshaker service. Note that
+		// this connection stays open until the application is closed.
+		// Disable the service config to avoid unnecessary TXT record lookups that
+		// cause timeouts with some versions of systemd-resolved.
+		var err error
+		opts := []grpc.DialOption{
+			grpc.WithTransportCredentials(insecure.NewCredentials()),
+			grpc.WithDisableServiceConfig(),
+		}
+		if envconfig.ALTSHandshakerKeepaliveParams {
+			opts = append(opts, grpc.WithKeepaliveParams(keepalive.ClientParameters{
+				Timeout: 10 * time.Second,
+				Time:    10 * time.Minute,
+			}))
+		}
+		hsConn, err = grpc.NewClient(hsAddress, opts...)
+		if err != nil {
+			return nil, err
+		}
+		hsConnMap[hsAddress] = hsConn
+	}
+	return hsConn, nil
+}
+
+// CloseForTesting closes all open connections to the handshaker service.
+//
+// For testing purposes only.
+func CloseForTesting() error {
+	for _, hsConn := range hsConnMap {
+		if hsConn == nil {
+			continue
+		}
+		if err := hsConn.Close(); err != nil {
+			return err
+		}
+	}
+
+	// Reset the connection map.
+	hsConnMap = make(map[string]*grpc.ClientConn)
+	return nil
+}

credentials/alts/internal/handshaker/service/service_test.go

@@ -0,0 +1,80 @@
+/*
+ *
+ * Copyright 2018 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package service
+
+import (
+	"testing"
+
+	"google.golang.org/grpc/internal/grpctest"
+)
+
+type s struct {
+	grpctest.Tester
+}
+
+func Test(t *testing.T) {
+	grpctest.RunSubTests(t, s{})
+}
+
+const (
+	testAddress1 = "some_address_1"
+	testAddress2 = "some_address_2"
+)
+
+// TestDial verifies the behaviour of alts handshake when there are multiple Dials.
+// If a connection has already been established, this function returns it.
+// Otherwise, a new connection is created.
+func (s) TestDial(t *testing.T) {
+	// First call to Dial, it should create a connection to the server running
+	// at the given address.
+	conn1, err := Dial(testAddress1)
+	if err != nil {
+		t.Fatalf("first call to Dial(%v) failed: %v", testAddress1, err)
+	}
+	defer conn1.Close()
+	if got, want := hsConnMap[testAddress1], conn1; got != want {
+		t.Fatalf("hsConnMap[%v]=%v, want %v", testAddress1, got, want)
+	}
+
+	// Second call to Dial should return conn1 above.
+	conn2, err := Dial(testAddress1)
+	if err != nil {
+		t.Fatalf("second call to Dial(%v) failed: %v", testAddress1, err)
+	}
+	defer conn2.Close()
+	if got, want := conn2, conn1; got != want {
+		t.Fatalf("second call to Dial(%v)=(%v, _), want (%v,. _)", testAddress1, got, want)
+	}
+	if got, want := hsConnMap[testAddress1], conn1; got != want {
+		t.Fatalf("hsConnMap[%v]=%v, want %v", testAddress1, got, want)
+	}
+
+	// Third call to Dial using a different address should create a new connection.
+	conn3, err := Dial(testAddress2)
+	if err != nil {
+		t.Fatalf("third call to Dial(%v) failed: %v", testAddress2, err)
+	}
+	defer conn3.Close()
+	if got, want := hsConnMap[testAddress2], conn3; got != want {
+		t.Fatalf("hsConnMap[%v]=%v, want %v", testAddress2, got, want)
+	}
+	if got, want := conn2 == conn3, false; got != want {
+		t.Fatalf("(conn2==conn3)=%v, want %v", got, want)
+	}
+}