...

Text file src/github.com/google/s2a-go/internal/proto/s2a/s2a.proto

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

     1// Copyright 2021 Google LLC
     2//
     3// Licensed under the Apache License, Version 2.0 (the "License");
     4// you may not use this file except in compliance with the License.
     5// You may obtain a copy of the License at
     6//
     7//    https://www.apache.org/licenses/LICENSE-2.0
     8//
     9// Unless required by applicable law or agreed to in writing, software
    10// distributed under the License is distributed on an "AS IS" BASIS,
    11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12// See the License for the specific language governing permissions and
    13// limitations under the License.
    14
    15syntax = "proto3";
    16
    17package s2a.proto;
    18
    19option go_package = "github.com/google/s2a/internal/proto/s2a_go_proto";
    20
    21import "internal/proto/common/common.proto";
    22
    23message AuthenticationMechanism {
    24  // (Optional) Application may specify an identity associated to an
    25  // authentication mechanism. Otherwise, S2A assumes that the authentication
    26  // mechanism is associated with the default identity. If the default identity
    27  // cannot be determined, session setup fails.
    28  Identity identity = 1;
    29
    30  oneof mechanism_oneof {
    31    // A token that the application uses to authenticate itself to the S2A.
    32    string token = 2;
    33  }
    34}
    35
    36message ClientSessionStartReq {
    37  // The application protocols supported by the client, e.g., "grpc".
    38  repeated string application_protocols = 1;
    39
    40  // (Optional) The minimum TLS version number that the S2A's handshaker module
    41  // will use to set up the session. If this field is not provided, S2A will use
    42  // the minimum version it supports.
    43  TLSVersion min_tls_version = 2;
    44
    45  // (Optional) The maximum TLS version number that the S2A's handshaker module
    46  // will use to set up the session. If this field is not provided, S2A will use
    47  // the maximum version it supports.
    48  TLSVersion max_tls_version = 3;
    49
    50  // The TLS ciphersuites that the client is willing to support.
    51  repeated Ciphersuite tls_ciphersuites = 4;
    52
    53  // (Optional) Describes which server identities are acceptable by the client.
    54  // If target identities are provided and none of them matches the peer
    55  // identity of the server, session setup fails.
    56  repeated Identity target_identities = 5;
    57
    58  // (Optional) Application may specify a local identity. Otherwise, S2A chooses
    59  // the default local identity. If the default identity cannot be determined,
    60  // session setup fails.
    61  Identity local_identity = 6;
    62
    63  // The target name that is used by S2A to configure SNI in the TLS handshake.
    64  // It is also used to perform server authorization check if avaiable. This
    65  // check is intended to verify that the peer authenticated identity is
    66  // authorized to run a service with the target name.
    67  // This field MUST only contain the host portion of the server address. It
    68  // MUST not contain the scheme or the port number. For example, if the server
    69  // address is dns://www.example.com:443, the value of this field should be
    70  // set to www.example.com.
    71  string target_name = 7;
    72}
    73
    74message ServerSessionStartReq {
    75  // The application protocols supported by the server, e.g., "grpc".
    76  repeated string application_protocols = 1;
    77
    78  // (Optional) The minimum TLS version number that the S2A's handshaker module
    79  // will use to set up the session. If this field is not provided, S2A will use
    80  // the minimum version it supports.
    81  TLSVersion min_tls_version = 2;
    82
    83  // (Optional) The maximum TLS version number that the S2A's handshaker module
    84  // will use to set up the session. If this field is not provided, S2A will use
    85  // the maximum version it supports.
    86  TLSVersion max_tls_version = 3;
    87
    88  // The TLS ciphersuites that the server is willing to support.
    89  repeated Ciphersuite tls_ciphersuites = 4;
    90
    91  // (Optional) A list of local identities supported by the server, if
    92  // specified. Otherwise, S2A chooses the default local identity. If the
    93  // default identity cannot be determined, session setup fails.
    94  repeated Identity local_identities = 5;
    95
    96  // The byte representation of the first handshake message received from the
    97  // client peer. It is possible that this first message is split into multiple
    98  // chunks. In this case, the first chunk is sent using this field and the
    99  // following chunks are sent using the in_bytes field of SessionNextReq
   100  // Specifically, if the client peer is using S2A, this field contains the
   101  // bytes in the out_frames field of SessionResp message that the client peer
   102  // received from its S2A after initiating the handshake.
   103  bytes in_bytes = 6;
   104}
   105
   106message SessionNextReq {
   107  // The byte representation of session setup, i.e., handshake messages.
   108  // Specifically:
   109  //  - All handshake messages sent from the server to the client.
   110  //  - All, except for the first, handshake messages sent from the client to
   111  //    the server. Note that the first message is communicated to S2A using the
   112  //    in_bytes field of ServerSessionStartReq.
   113  // If the peer is using S2A, this field contains the bytes in the out_frames
   114  // field of SessionResp message that the peer received from its S2A.
   115  bytes in_bytes = 1;
   116}
   117
   118message ResumptionTicketReq {
   119  // The byte representation of a NewSessionTicket message received from the
   120  // server.
   121  repeated bytes in_bytes = 1;
   122
   123  // A connection identifier that was created and sent by S2A at the end of a
   124  // handshake.
   125  uint64 connection_id = 2;
   126
   127  // The local identity that was used by S2A during session setup and included
   128  // in |SessionResult|.
   129  Identity local_identity = 3;
   130}
   131
   132message SessionReq {
   133  oneof req_oneof {
   134    // The client session setup request message.
   135    ClientSessionStartReq client_start = 1;
   136
   137    // The server session setup request message.
   138    ServerSessionStartReq server_start = 2;
   139
   140    // The next session setup message request message.
   141    SessionNextReq next = 3;
   142
   143    // The resumption ticket that is received from the server. This message is
   144    // only accepted by S2A if it is running as a client and if it is received
   145    // after session setup is complete. If S2A is running as a server and it
   146    // receives this message, the session is terminated.
   147    ResumptionTicketReq resumption_ticket = 4;
   148  }
   149
   150  // (Optional) The authentication mechanisms that the client wishes to use to
   151  // authenticate to the S2A, ordered by preference. The S2A will always use the
   152  // first authentication mechanism that appears in the list and is supported by
   153  // the S2A.
   154  repeated AuthenticationMechanism auth_mechanisms = 5;
   155}
   156
   157message SessionState {
   158  // The TLS version number that the S2A's handshaker module used to set up the
   159  // session.
   160  TLSVersion tls_version = 1;
   161
   162  // The TLS ciphersuite negotiated by the S2A's handshaker module.
   163  Ciphersuite tls_ciphersuite = 2;
   164
   165  // The sequence number of the next, incoming, TLS record.
   166  uint64 in_sequence = 3;
   167  // The sequence number of the next, outgoing, TLS record.
   168  uint64 out_sequence = 4;
   169
   170  // The key for the inbound direction.
   171  bytes in_key = 5;
   172  // The key for the outbound direction.
   173  bytes out_key = 6;
   174
   175  // The constant part of the record nonce for the outbound direction.
   176  bytes in_fixed_nonce = 7;
   177  // The constant part of the record nonce for the inbound direction.
   178  bytes out_fixed_nonce = 8;
   179
   180  // A connection identifier that can be provided to S2A to perform operations
   181  // related to this connection. This identifier will be stored by the record
   182  // protocol, and included in the |ResumptionTicketReq| message that is later
   183  // sent back to S2A. This field is set only for client-side connections.
   184  uint64 connection_id = 9;
   185
   186  // Set to true if a cached session was reused to do an abbreviated handshake.
   187  bool is_handshake_resumed = 10;
   188}
   189
   190message SessionResult {
   191  // The application protocol negotiated for this session.
   192  string application_protocol = 1;
   193
   194  // The session state at the end. This state contains all cryptographic
   195  // material required to initialize the record protocol object.
   196  SessionState state = 2;
   197
   198  // The authenticated identity of the peer.
   199  Identity peer_identity = 4;
   200
   201  // The local identity used during session setup. This could be:
   202  // - The local identity that the client specifies in ClientSessionStartReq.
   203  // - One of the local identities that the server specifies in
   204  //   ServerSessionStartReq.
   205  // - If neither client or server specifies local identities, the S2A picks the
   206  //   default one. In this case, this field will contain that identity.
   207  Identity local_identity = 5;
   208
   209  // The SHA256 hash of the local certificate used in the handshake.
   210  bytes local_cert_fingerprint = 6;
   211
   212  // The SHA256 hash of the peer certificate used in the handshake.
   213  bytes peer_cert_fingerprint = 7;
   214}
   215
   216message SessionStatus {
   217  // The status code that is specific to the application and the implementation
   218  // of S2A, e.g., gRPC status code.
   219  uint32 code = 1;
   220
   221  // The status details.
   222  string details = 2;
   223}
   224
   225message SessionResp {
   226  // The local identity used during session setup. This could be:
   227  // - The local identity that the client specifies in ClientSessionStartReq.
   228  // - One of the local identities that the server specifies in
   229  //   ServerSessionStartReq.
   230  // - If neither client or server specifies local identities, the S2A picks the
   231  //   default one. In this case, this field will contain that identity.
   232  // If the SessionResult is populated, then this must coincide with the local
   233  // identity specified in the SessionResult; otherwise, the handshake must
   234  // fail.
   235  Identity local_identity = 1;
   236
   237  // The byte representation of the frames that should be sent to the peer. May
   238  // be empty if nothing needs to be sent to the peer or if in_bytes in the
   239  // SessionReq is incomplete. All bytes in a non-empty out_frames must be sent
   240  // to the peer even if the session setup status is not OK as these frames may
   241  // contain appropriate alerts.
   242  bytes out_frames = 2;
   243
   244  // Number of bytes in the in_bytes field that are consumed by S2A. It is
   245  // possible that part of in_bytes is unrelated to the session setup process.
   246  uint32 bytes_consumed = 3;
   247
   248  // This is set if the session is successfully set up. out_frames may
   249  // still be set to frames that needs to be forwarded to the peer.
   250  SessionResult result = 4;
   251
   252  // Status of session setup at the current stage.
   253  SessionStatus status = 5;
   254}
   255
   256service S2AService {
   257  // S2A service accepts a stream of session setup requests and returns a stream
   258  // of session setup responses. The client of this service is expected to send
   259  // exactly one client_start or server_start message followed by at least one
   260  // next message. Applications running TLS clients can send requests with
   261  // resumption_ticket messages only after the session is successfully set up.
   262  //
   263  // Every time S2A client sends a request, this service sends a response.
   264  // However, clients do not have to wait for service response before sending
   265  // the next request.
   266  rpc SetUpSession(stream SessionReq) returns (stream SessionResp) {}
   267}

View as plain text