// 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 // // https://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 s2a.proto; option go_package = "github.com/google/s2a/internal/proto/s2a_go_proto"; import "internal/proto/common/common.proto"; message AuthenticationMechanism { // (Optional) Application may specify an identity associated to an // authentication mechanism. Otherwise, S2A assumes that the authentication // mechanism is associated with the default identity. If the default identity // cannot be determined, session setup fails. Identity identity = 1; oneof mechanism_oneof { // A token that the application uses to authenticate itself to the S2A. string token = 2; } } message ClientSessionStartReq { // The application protocols supported by the client, e.g., "grpc". repeated string application_protocols = 1; // (Optional) The minimum TLS version number that the S2A's handshaker module // will use to set up the session. If this field is not provided, S2A will use // the minimum version it supports. TLSVersion min_tls_version = 2; // (Optional) The maximum TLS version number that the S2A's handshaker module // will use to set up the session. If this field is not provided, S2A will use // the maximum version it supports. TLSVersion max_tls_version = 3; // The TLS ciphersuites that the client is willing to support. repeated Ciphersuite tls_ciphersuites = 4; // (Optional) Describes which server identities are acceptable by the client. // If target identities are provided and none of them matches the peer // identity of the server, session setup fails. repeated Identity target_identities = 5; // (Optional) Application may specify a local identity. Otherwise, S2A chooses // the default local identity. If the default identity cannot be determined, // session setup fails. Identity local_identity = 6; // The target name that is used by S2A to configure SNI in the TLS handshake. // It is also used to perform server authorization check if avaiable. This // check is intended to verify that the peer authenticated identity is // authorized to run a service with the target name. // This field MUST only contain the host portion of the server address. It // MUST not contain the scheme or the port number. For example, if the server // address is dns://www.example.com:443, the value of this field should be // set to www.example.com. string target_name = 7; } message ServerSessionStartReq { // The application protocols supported by the server, e.g., "grpc". repeated string application_protocols = 1; // (Optional) The minimum TLS version number that the S2A's handshaker module // will use to set up the session. If this field is not provided, S2A will use // the minimum version it supports. TLSVersion min_tls_version = 2; // (Optional) The maximum TLS version number that the S2A's handshaker module // will use to set up the session. If this field is not provided, S2A will use // the maximum version it supports. TLSVersion max_tls_version = 3; // The TLS ciphersuites that the server is willing to support. repeated Ciphersuite tls_ciphersuites = 4; // (Optional) A list of local identities supported by the server, if // specified. Otherwise, S2A chooses the default local identity. If the // default identity cannot be determined, session setup fails. repeated Identity local_identities = 5; // The byte representation of the first handshake message received from the // client peer. It is possible that this first message is split into multiple // chunks. In this case, the first chunk is sent using this field and the // following chunks are sent using the in_bytes field of SessionNextReq // Specifically, if the client peer is using S2A, this field contains the // bytes in the out_frames field of SessionResp message that the client peer // received from its S2A after initiating the handshake. bytes in_bytes = 6; } message SessionNextReq { // The byte representation of session setup, i.e., handshake messages. // Specifically: // - All handshake messages sent from the server to the client. // - All, except for the first, handshake messages sent from the client to // the server. Note that the first message is communicated to S2A using the // in_bytes field of ServerSessionStartReq. // If the peer is using S2A, this field contains the bytes in the out_frames // field of SessionResp message that the peer received from its S2A. bytes in_bytes = 1; } message ResumptionTicketReq { // The byte representation of a NewSessionTicket message received from the // server. repeated bytes in_bytes = 1; // A connection identifier that was created and sent by S2A at the end of a // handshake. uint64 connection_id = 2; // The local identity that was used by S2A during session setup and included // in |SessionResult|. Identity local_identity = 3; } message SessionReq { oneof req_oneof { // The client session setup request message. ClientSessionStartReq client_start = 1; // The server session setup request message. ServerSessionStartReq server_start = 2; // The next session setup message request message. SessionNextReq next = 3; // The resumption ticket that is received from the server. This message is // only accepted by S2A if it is running as a client and if it is received // after session setup is complete. If S2A is running as a server and it // receives this message, the session is terminated. ResumptionTicketReq resumption_ticket = 4; } // (Optional) The authentication mechanisms that the client wishes to use to // authenticate to the S2A, ordered by preference. The S2A will always use the // first authentication mechanism that appears in the list and is supported by // the S2A. repeated AuthenticationMechanism auth_mechanisms = 5; } message SessionState { // The TLS version number that the S2A's handshaker module used to set up the // session. TLSVersion tls_version = 1; // The TLS ciphersuite negotiated by the S2A's handshaker module. Ciphersuite tls_ciphersuite = 2; // The sequence number of the next, incoming, TLS record. uint64 in_sequence = 3; // The sequence number of the next, outgoing, TLS record. uint64 out_sequence = 4; // The key for the inbound direction. bytes in_key = 5; // The key for the outbound direction. bytes out_key = 6; // The constant part of the record nonce for the outbound direction. bytes in_fixed_nonce = 7; // The constant part of the record nonce for the inbound direction. bytes out_fixed_nonce = 8; // A connection identifier that can be provided to S2A to perform operations // related to this connection. This identifier will be stored by the record // protocol, and included in the |ResumptionTicketReq| message that is later // sent back to S2A. This field is set only for client-side connections. uint64 connection_id = 9; // Set to true if a cached session was reused to do an abbreviated handshake. bool is_handshake_resumed = 10; } message SessionResult { // The application protocol negotiated for this session. string application_protocol = 1; // The session state at the end. This state contains all cryptographic // material required to initialize the record protocol object. SessionState state = 2; // The authenticated identity of the peer. Identity peer_identity = 4; // The local identity used during session setup. This could be: // - The local identity that the client specifies in ClientSessionStartReq. // - One of the local identities that the server specifies in // ServerSessionStartReq. // - If neither client or server specifies local identities, the S2A picks the // default one. In this case, this field will contain that identity. Identity local_identity = 5; // The SHA256 hash of the local certificate used in the handshake. bytes local_cert_fingerprint = 6; // The SHA256 hash of the peer certificate used in the handshake. bytes peer_cert_fingerprint = 7; } message SessionStatus { // The status code that is specific to the application and the implementation // of S2A, e.g., gRPC status code. uint32 code = 1; // The status details. string details = 2; } message SessionResp { // The local identity used during session setup. This could be: // - The local identity that the client specifies in ClientSessionStartReq. // - One of the local identities that the server specifies in // ServerSessionStartReq. // - If neither client or server specifies local identities, the S2A picks the // default one. In this case, this field will contain that identity. // If the SessionResult is populated, then this must coincide with the local // identity specified in the SessionResult; otherwise, the handshake must // fail. Identity local_identity = 1; // The byte representation of the frames that should be sent to the peer. May // be empty if nothing needs to be sent to the peer or if in_bytes in the // SessionReq is incomplete. All bytes in a non-empty out_frames must be sent // to the peer even if the session setup status is not OK as these frames may // contain appropriate alerts. bytes out_frames = 2; // Number of bytes in the in_bytes field that are consumed by S2A. It is // possible that part of in_bytes is unrelated to the session setup process. uint32 bytes_consumed = 3; // This is set if the session is successfully set up. out_frames may // still be set to frames that needs to be forwarded to the peer. SessionResult result = 4; // Status of session setup at the current stage. SessionStatus status = 5; } service S2AService { // S2A service accepts a stream of session setup requests and returns a stream // of session setup responses. The client of this service is expected to send // exactly one client_start or server_start message followed by at least one // next message. Applications running TLS clients can send requests with // resumption_ticket messages only after the session is successfully set up. // // Every time S2A client sends a request, this service sends a response. // However, clients do not have to wait for service response before sending // the next request. rpc SetUpSession(stream SessionReq) returns (stream SessionResp) {} }