1// Copyright 2022 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.v2;
18
19option go_package = "github.com/google/s2a/internal/proto/v2/s2a_go_proto";
20
21import "internal/proto/common/common.proto";
22import "internal/proto/v2/common/common.proto";
23import "internal/proto/v2/s2a_context/s2a_context.proto";
24
25enum SignatureAlgorithm {
26 S2A_SSL_SIGN_UNSPECIFIED = 0;
27 // RSA Public-Key Cryptography Standards #1.
28 S2A_SSL_SIGN_RSA_PKCS1_SHA256 = 1;
29 S2A_SSL_SIGN_RSA_PKCS1_SHA384 = 2;
30 S2A_SSL_SIGN_RSA_PKCS1_SHA512 = 3;
31 // ECDSA.
32 S2A_SSL_SIGN_ECDSA_SECP256R1_SHA256 = 4;
33 S2A_SSL_SIGN_ECDSA_SECP384R1_SHA384 = 5;
34 S2A_SSL_SIGN_ECDSA_SECP521R1_SHA512 = 6;
35 // RSA Probabilistic Signature Scheme.
36 S2A_SSL_SIGN_RSA_PSS_RSAE_SHA256 = 7;
37 S2A_SSL_SIGN_RSA_PSS_RSAE_SHA384 = 8;
38 S2A_SSL_SIGN_RSA_PSS_RSAE_SHA512 = 9;
39 // ED25519.
40 S2A_SSL_SIGN_ED25519 = 10;
41}
42
43message AlpnPolicy {
44 // If true, the application MUST perform ALPN negotiation.
45 bool enable_alpn_negotiation = 1;
46
47 // The ordered list of ALPN protocols that specify how the application SHOULD
48 // negotiate ALPN during the TLS handshake.
49 //
50 // The application MAY ignore any ALPN protocols in this list that are not
51 // supported by the application.
52 repeated AlpnProtocol alpn_protocols = 2;
53}
54
55message AuthenticationMechanism {
56 // Applications may specify an identity associated to an authentication
57 // mechanism. Otherwise, S2A assumes that the authentication mechanism is
58 // associated with the default identity. If the default identity cannot be
59 // determined, the request is rejected.
60 s2a.proto.Identity identity = 1;
61
62 oneof mechanism_oneof {
63 // A token that the application uses to authenticate itself to S2A.
64 string token = 2;
65 }
66}
67
68message Status {
69 // The status code that is specific to the application and the implementation
70 // of S2A, e.g., gRPC status code.
71 uint32 code = 1;
72
73 // The status details.
74 string details = 2;
75}
76
77message GetTlsConfigurationReq {
78 // The role of the application in the TLS connection.
79 ConnectionSide connection_side = 1;
80
81 // The server name indication (SNI) extension, which MAY be populated when a
82 // server is offloading to S2A. The SNI is used to determine the server
83 // identity if the local identity in the request is empty.
84 string sni = 2;
85}
86
87message GetTlsConfigurationResp {
88 // Next ID: 8
89 message ClientTlsConfiguration {
90 reserved 4, 5;
91
92 // The certificate chain that the client MUST use for the TLS handshake.
93 // It's a list of PEM-encoded certificates, ordered from leaf to root,
94 // excluding the root.
95 repeated string certificate_chain = 1;
96
97 // The minimum TLS version number that the client MUST use for the TLS
98 // handshake. If this field is not provided, the client MUST use the default
99 // minimum version of the client's TLS library.
100 TLSVersion min_tls_version = 2;
101
102 // The maximum TLS version number that the client MUST use for the TLS
103 // handshake. If this field is not provided, the client MUST use the default
104 // maximum version of the client's TLS library.
105 TLSVersion max_tls_version = 3;
106
107 // The ordered list of TLS 1.0-1.2 ciphersuites that the client MAY offer to
108 // negotiate in the TLS handshake.
109 repeated Ciphersuite ciphersuites = 6;
110
111 // The policy that dictates how the client negotiates ALPN during the TLS
112 // handshake.
113 AlpnPolicy alpn_policy = 7;
114 }
115
116 // Next ID: 12
117 message ServerTlsConfiguration {
118 reserved 4, 5;
119
120 enum RequestClientCertificate {
121 UNSPECIFIED = 0;
122 DONT_REQUEST_CLIENT_CERTIFICATE = 1;
123 REQUEST_CLIENT_CERTIFICATE_BUT_DONT_VERIFY = 2;
124 REQUEST_CLIENT_CERTIFICATE_AND_VERIFY = 3;
125 REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_BUT_DONT_VERIFY = 4;
126 REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_AND_VERIFY = 5;
127 }
128
129 // The certificate chain that the server MUST use for the TLS handshake.
130 // It's a list of PEM-encoded certificates, ordered from leaf to root,
131 // excluding the root.
132 repeated string certificate_chain = 1;
133
134 // The minimum TLS version number that the server MUST use for the TLS
135 // handshake. If this field is not provided, the server MUST use the default
136 // minimum version of the server's TLS library.
137 TLSVersion min_tls_version = 2;
138
139 // The maximum TLS version number that the server MUST use for the TLS
140 // handshake. If this field is not provided, the server MUST use the default
141 // maximum version of the server's TLS library.
142 TLSVersion max_tls_version = 3;
143
144 // The ordered list of TLS 1.0-1.2 ciphersuites that the server MAY offer to
145 // negotiate in the TLS handshake.
146 repeated Ciphersuite ciphersuites = 10;
147
148 // Whether to enable TLS resumption.
149 bool tls_resumption_enabled = 6;
150
151 // Whether the server MUST request a client certificate (i.e. to negotiate
152 // TLS vs. mTLS).
153 RequestClientCertificate request_client_certificate = 7;
154
155 // Returns the maximum number of extra bytes that
156 // |OffloadResumptionKeyOperation| can add to the number of unencrypted
157 // bytes to form the encrypted bytes.
158 uint32 max_overhead_of_ticket_aead = 9;
159
160 // The policy that dictates how the server negotiates ALPN during the TLS
161 // handshake.
162 AlpnPolicy alpn_policy = 11;
163 }
164
165 oneof tls_configuration {
166 ClientTlsConfiguration client_tls_configuration = 1;
167 ServerTlsConfiguration server_tls_configuration = 2;
168 }
169}
170
171message OffloadPrivateKeyOperationReq {
172 enum PrivateKeyOperation {
173 UNSPECIFIED = 0;
174 // When performing a TLS 1.2 or 1.3 handshake, the (partial) transcript of
175 // the TLS handshake must be signed to prove possession of the private key.
176 //
177 // See https://www.rfc-editor.org/rfc/rfc8446.html#section-4.4.3.
178 SIGN = 1;
179 // When performing a TLS 1.2 handshake using an RSA algorithm, the key
180 // exchange algorithm involves the client generating a premaster secret,
181 // encrypting it using the server's public key, and sending this encrypted
182 // blob to the server in a ClientKeyExchange message.
183 //
184 // See https://www.rfc-editor.org/rfc/rfc4346#section-7.4.7.1.
185 DECRYPT = 2;
186 }
187
188 // The operation the private key is used for.
189 PrivateKeyOperation operation = 1;
190
191 // The signature algorithm to be used for signing operations.
192 SignatureAlgorithm signature_algorithm = 2;
193
194 // The input bytes to be signed or decrypted.
195 oneof in_bytes {
196 // Raw bytes to be hashed and signed, or decrypted.
197 bytes raw_bytes = 4;
198 // A SHA256 hash to be signed. Must be 32 bytes.
199 bytes sha256_digest = 5;
200 // A SHA384 hash to be signed. Must be 48 bytes.
201 bytes sha384_digest = 6;
202 // A SHA512 hash to be signed. Must be 64 bytes.
203 bytes sha512_digest = 7;
204 }
205}
206
207message OffloadPrivateKeyOperationResp {
208 // The signed or decrypted output bytes.
209 bytes out_bytes = 1;
210}
211
212message OffloadResumptionKeyOperationReq {
213 enum ResumptionKeyOperation {
214 UNSPECIFIED = 0;
215 ENCRYPT = 1;
216 DECRYPT = 2;
217 }
218
219 // The operation the resumption key is used for.
220 ResumptionKeyOperation operation = 1;
221
222 // The bytes to be encrypted or decrypted.
223 bytes in_bytes = 2;
224}
225
226message OffloadResumptionKeyOperationResp {
227 // The encrypted or decrypted bytes.
228 bytes out_bytes = 1;
229}
230
231message ValidatePeerCertificateChainReq {
232 enum VerificationMode {
233 // The default verification mode supported by S2A.
234 UNSPECIFIED = 0;
235 // The SPIFFE verification mode selects the set of trusted certificates to
236 // use for path building based on the SPIFFE trust domain in the peer's leaf
237 // certificate.
238 SPIFFE = 1;
239 // The connect-to-Google verification mode uses the trust bundle for
240 // connecting to Google, e.g. *.mtls.googleapis.com endpoints.
241 CONNECT_TO_GOOGLE = 2;
242 }
243
244 message ClientPeer {
245 // The certificate chain to be verified. The chain MUST be a list of
246 // DER-encoded certificates, ordered from leaf to root, excluding the root.
247 repeated bytes certificate_chain = 1;
248 }
249
250 message ServerPeer {
251 // The certificate chain to be verified. The chain MUST be a list of
252 // DER-encoded certificates, ordered from leaf to root, excluding the root.
253 repeated bytes certificate_chain = 1;
254
255 // The expected hostname of the server.
256 string server_hostname = 2;
257
258 // The UnrestrictedClientPolicy specified by the user.
259 bytes serialized_unrestricted_client_policy = 3;
260 }
261
262 // The verification mode that S2A MUST use to validate the peer certificate
263 // chain.
264 VerificationMode mode = 1;
265
266 oneof peer_oneof {
267 ClientPeer client_peer = 2;
268 ServerPeer server_peer = 3;
269 }
270}
271
272message ValidatePeerCertificateChainResp {
273 enum ValidationResult {
274 UNSPECIFIED = 0;
275 SUCCESS = 1;
276 FAILURE = 2;
277 }
278
279 // The result of validating the peer certificate chain.
280 ValidationResult validation_result = 1;
281
282 // The validation details. This field is only populated when the validation
283 // result is NOT SUCCESS.
284 string validation_details = 2;
285
286 // The S2A context contains information from the peer certificate chain.
287 //
288 // The S2A context MAY be populated even if validation of the peer certificate
289 // chain fails.
290 S2AContext context = 3;
291}
292
293message SessionReq {
294 // The identity corresponding to the TLS configurations that MUST be used for
295 // the TLS handshake.
296 //
297 // If a managed identity already exists, the local identity and authentication
298 // mechanisms are ignored. If a managed identity doesn't exist and the local
299 // identity is not populated, S2A will try to deduce the managed identity to
300 // use from the SNI extension. If that also fails, S2A uses the default
301 // identity (if one exists).
302 s2a.proto.Identity local_identity = 1;
303
304 // The authentication mechanisms that the application wishes to use to
305 // authenticate to S2A, ordered by preference. S2A will always use the first
306 // authentication mechanism that matches the managed identity.
307 repeated AuthenticationMechanism authentication_mechanisms = 2;
308
309 oneof req_oneof {
310 // Requests the certificate chain and TLS configuration corresponding to the
311 // local identity, which the application MUST use to negotiate the TLS
312 // handshake.
313 GetTlsConfigurationReq get_tls_configuration_req = 3;
314
315 // Signs or decrypts the input bytes using a private key corresponding to
316 // the local identity in the request.
317 //
318 // WARNING: More than one OffloadPrivateKeyOperationReq may be sent to the
319 // S2Av2 by a server during a TLS 1.2 handshake.
320 OffloadPrivateKeyOperationReq offload_private_key_operation_req = 4;
321
322 // Encrypts or decrypts the input bytes using a resumption key corresponding
323 // to the local identity in the request.
324 OffloadResumptionKeyOperationReq offload_resumption_key_operation_req = 5;
325
326 // Verifies the peer's certificate chain using
327 // (a) trust bundles corresponding to the local identity in the request, and
328 // (b) the verification mode in the request.
329 ValidatePeerCertificateChainReq validate_peer_certificate_chain_req = 6;
330 }
331}
332
333message SessionResp {
334 // Status of the session response.
335 //
336 // The status field is populated so that if an error occurs when making an
337 // individual request, then communication with the S2A may continue. If an
338 // error is returned directly (e.g. at the gRPC layer), then it may result
339 // that the bidirectional stream being closed.
340 Status status = 1;
341
342 oneof resp_oneof {
343 // Contains the certificate chain and TLS configurations corresponding to
344 // the local identity.
345 GetTlsConfigurationResp get_tls_configuration_resp = 2;
346
347 // Contains the signed or encrypted output bytes using the private key
348 // corresponding to the local identity.
349 OffloadPrivateKeyOperationResp offload_private_key_operation_resp = 3;
350
351 // Contains the encrypted or decrypted output bytes using the resumption key
352 // corresponding to the local identity.
353 OffloadResumptionKeyOperationResp offload_resumption_key_operation_resp = 4;
354
355 // Contains the validation result, peer identity and fingerprints of peer
356 // certificates.
357 ValidatePeerCertificateChainResp validate_peer_certificate_chain_resp = 5;
358 }
359}
360
361service S2AService {
362 // SetUpSession is a bidirectional stream used by applications to offload
363 // operations from the TLS handshake.
364 rpc SetUpSession(stream SessionReq) returns (stream SessionResp) {}
365}
View as plain text