proto/secure_session.proto

// Copyright 2021 Google LLC
//
// 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.

syntax = "proto3";

package stet.proto;

import "google/api/annotations.proto";

option go_package = "github.com/GoogleCloudPlatform/stet/proto/secure_session_go_proto";

service ConfidentialEkmSessionEstablishmentService {
  // Endpoint to initialize a TLS secure session between a client and EKM.
  rpc BeginSession(BeginSessionRequest) returns (BeginSessionResponse) {
    option (google.api.http) = {
      post: "/v0/session/begin-session"
      body: "*"
    };
  }

  // Endpoint to continue secure session establishment.
  rpc Handshake(HandshakeRequest) returns (HandshakeResponse) {
    option (google.api.http) = {
      post: "/v0/session/handshake"
      body: "*"
    };
  }

  // Endpoint for asking the server what attestation evidence is acceptable to
  // send as part of the Finalize step.
  rpc NegotiateAttestation(NegotiateAttestationRequest)
      returns (NegotiateAttestationResponse) {
    option (google.api.http) = {
      post: "/v0/session/negotiate-attestations"
      body: "*"
    };
  }

  // Endpoint for finalizing the secure session handshake by means of a client
  // presenting the previously negotiated attestation evidence.
  rpc Finalize(FinalizeRequest) returns (FinalizeResponse) {
    option (google.api.http) = {
      post: "/v0/session/finalize"
      body: "*"
    };
  }

  // Endpoint for explicitly ending a previously established secure session.
  rpc EndSession(EndSessionRequest) returns (EndSessionResponse) {
    option (google.api.http) = {
      post: "/v0/session/end-session"
      body: "*"
    };
  }
}

message BeginSessionRequest {
  // TLS records containing the initial handshake message from client to server.
  // Required.
  bytes tls_records = 1;
}

message BeginSessionResponse {
  // Opaque context that identifies a client/server session. Required.
  bytes session_context = 1;

  // TLS records containing the initial handshake response from server to
  // client. Required.
  bytes tls_records = 2;
}

message HandshakeRequest {
  // Opaque context that identifies a client/server session. Required.
  bytes session_context = 1;

  // TLS records containing the client handshake message to the server.
  // Required.
  bytes tls_records = 2;
}

message HandshakeResponse {
  // TLS records containing the server handshake message to the client.
  // Required.
  bytes tls_records = 1;
}

message NegotiateAttestationRequest {
  // Opaque context that identifies a client/server session. Required.
  bytes session_context = 1;

  // The ordered set of the kinds of attestation evidence that the client
  // supports, sorted by client preference. The server may optionally account
  // for the client's preferred attestation types. The server chooses one or
  // more options from this list, determining what evidence will be sent by the
  // client in the FinalizeRequest. The bytes are session records containing a
  // serialized AttestationEvidenceTypeList Required.
  bytes offered_evidence_types_records = 2;
}

message NegotiateAttestationResponse {
  // The evidence that must be supplied by the client in a FinalizeRequest. This
  // must be a subset of the offered_evidence_types_records supplied by a client
  // in a NegotiateAttestationRequest. The bytes are session records containing
  // a serialized AttestationEvidenceTypeList Required.
  bytes required_evidence_types_records = 1;
}

message FinalizeRequest {
  // Opaque context that identifies a client/server session. Required.
  bytes session_context = 1;

  // Session-encrypted, serialized client AttestationEvidence containing the
  // exported keying material generated with the label "EXPERIMENTAL Google
  // Confidential Computing Client Attestation 1.0". Optional.
  bytes attestation_evidence_records = 2;
}

message FinalizeResponse {}

message EndSessionRequest {
  // The session to end. Required.
  bytes session_context = 1;

  // The session-encrypted string "TLS Tunneled EndSessionRequest V1". Required.
  bytes tls_records = 2;
}

message EndSessionResponse {}