| 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 |
|
| 15 |
syntax = "proto3"; |
| 16 |
|
| 17 |
package s2a.proto; |
| 18 |
|
| 19 |
option go_package = "github.com/google/s2a/internal/proto/s2a_go_proto"; |
| 20 |
|
| 21 |
import "internal/proto/common/common.proto"; |
| 22 |
|
| 23 |
message 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 |
|
| 36 |
message 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 |
|
| 74 |
message 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 |
|
| 106 |
message 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 |
|
| 118 |
message 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 |
|
| 132 |
message 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 |
|
| 157 |
message 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 |
|
| 190 |
message 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 |
|
| 216 |
message 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 |
|
| 225 |
message 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 |
|
| 256 |
service 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 |
} |