Debian Codegraph @

internal/proto/v2/s2a/s2a.proto

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