| 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 |
} |