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