// Copyright 2022 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. syntax = "proto3"; package s2a.proto.v2; option go_package = "github.com/google/s2a/internal/proto/v2/s2a_go_proto"; import "internal/proto/v2/common/common.proto"; import "internal/proto/v2/s2a_context/s2a_context.proto"; enum SignatureAlgorithm { S2A_SSL_SIGN_UNSPECIFIED = 0; // RSA Public-Key Cryptography Standards #1. S2A_SSL_SIGN_RSA_PKCS1_SHA256 = 1; S2A_SSL_SIGN_RSA_PKCS1_SHA384 = 2; S2A_SSL_SIGN_RSA_PKCS1_SHA512 = 3; // ECDSA. S2A_SSL_SIGN_ECDSA_SECP256R1_SHA256 = 4; S2A_SSL_SIGN_ECDSA_SECP384R1_SHA384 = 5; S2A_SSL_SIGN_ECDSA_SECP521R1_SHA512 = 6; // RSA Probabilistic Signature Scheme. S2A_SSL_SIGN_RSA_PSS_RSAE_SHA256 = 7; S2A_SSL_SIGN_RSA_PSS_RSAE_SHA384 = 8; S2A_SSL_SIGN_RSA_PSS_RSAE_SHA512 = 9; // ED25519. S2A_SSL_SIGN_ED25519 = 10; } message AlpnPolicy { // If true, the application MUST perform ALPN negotiation. bool enable_alpn_negotiation = 1; // The ordered list of ALPN protocols that specify how the application SHOULD // negotiate ALPN during the TLS handshake. // // The application MAY ignore any ALPN protocols in this list that are not // supported by the application. repeated AlpnProtocol alpn_protocols = 2; } message AuthenticationMechanism { reserved 1; // Applications may specify an identity associated to an authentication // mechanism. Otherwise, S2A assumes that the authentication mechanism is // associated with the default identity. If the default identity cannot be // determined, the request is rejected. Identity identity = 3; oneof mechanism_oneof { // A token that the application uses to authenticate itself to S2A. string token = 2; } } message Status { // The status code that is specific to the application and the implementation // of S2A, e.g., gRPC status code. uint32 code = 1; // The status details. string details = 2; } message GetTlsConfigurationReq { // The role of the application in the TLS connection. ConnectionSide connection_side = 1; // The server name indication (SNI) extension, which MAY be populated when a // server is offloading to S2A. The SNI is used to determine the server // identity if the local identity in the request is empty. string sni = 2; } message GetTlsConfigurationResp { // Next ID: 8 message ClientTlsConfiguration { reserved 4, 5; // The certificate chain that the client MUST use for the TLS handshake. // It's a list of PEM-encoded certificates, ordered from leaf to root, // excluding the root. repeated string certificate_chain = 1; // The minimum TLS version number that the client MUST use for the TLS // handshake. If this field is not provided, the client MUST use the default // minimum version of the client's TLS library. TLSVersion min_tls_version = 2; // The maximum TLS version number that the client MUST use for the TLS // handshake. If this field is not provided, the client MUST use the default // maximum version of the client's TLS library. TLSVersion max_tls_version = 3; // The ordered list of TLS 1.0-1.2 ciphersuites that the client MAY offer to // negotiate in the TLS handshake. repeated Ciphersuite ciphersuites = 6; // The policy that dictates how the client negotiates ALPN during the TLS // handshake. AlpnPolicy alpn_policy = 7; } // Next ID: 12 message ServerTlsConfiguration { reserved 4, 5; enum RequestClientCertificate { UNSPECIFIED = 0; DONT_REQUEST_CLIENT_CERTIFICATE = 1; REQUEST_CLIENT_CERTIFICATE_BUT_DONT_VERIFY = 2; REQUEST_CLIENT_CERTIFICATE_AND_VERIFY = 3; REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_BUT_DONT_VERIFY = 4; REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_AND_VERIFY = 5; } // The certificate chain that the server MUST use for the TLS handshake. // It's a list of PEM-encoded certificates, ordered from leaf to root, // excluding the root. repeated string certificate_chain = 1; // The minimum TLS version number that the server MUST use for the TLS // handshake. If this field is not provided, the server MUST use the default // minimum version of the server's TLS library. TLSVersion min_tls_version = 2; // The maximum TLS version number that the server MUST use for the TLS // handshake. If this field is not provided, the server MUST use the default // maximum version of the server's TLS library. TLSVersion max_tls_version = 3; // The ordered list of TLS 1.0-1.2 ciphersuites that the server MAY offer to // negotiate in the TLS handshake. repeated Ciphersuite ciphersuites = 10; // Whether to enable TLS resumption. bool tls_resumption_enabled = 6; // Whether the server MUST request a client certificate (i.e. to negotiate // TLS vs. mTLS). RequestClientCertificate request_client_certificate = 7; // Returns the maximum number of extra bytes that // |OffloadResumptionKeyOperation| can add to the number of unencrypted // bytes to form the encrypted bytes. uint32 max_overhead_of_ticket_aead = 9; // The policy that dictates how the server negotiates ALPN during the TLS // handshake. AlpnPolicy alpn_policy = 11; } oneof tls_configuration { ClientTlsConfiguration client_tls_configuration = 1; ServerTlsConfiguration server_tls_configuration = 2; } } message OffloadPrivateKeyOperationReq { enum PrivateKeyOperation { UNSPECIFIED = 0; // When performing a TLS 1.2 or 1.3 handshake, the (partial) transcript of // the TLS handshake must be signed to prove possession of the private key. // // See https://www.rfc-editor.org/rfc/rfc8446.html#section-4.4.3. SIGN = 1; // When performing a TLS 1.2 handshake using an RSA algorithm, the key // exchange algorithm involves the client generating a premaster secret, // encrypting it using the server's public key, and sending this encrypted // blob to the server in a ClientKeyExchange message. // // See https://www.rfc-editor.org/rfc/rfc4346#section-7.4.7.1. DECRYPT = 2; } // The operation the private key is used for. PrivateKeyOperation operation = 1; // The signature algorithm to be used for signing operations. SignatureAlgorithm signature_algorithm = 2; // The input bytes to be signed or decrypted. oneof in_bytes { // Raw bytes to be hashed and signed, or decrypted. bytes raw_bytes = 4; // A SHA256 hash to be signed. Must be 32 bytes. bytes sha256_digest = 5; // A SHA384 hash to be signed. Must be 48 bytes. bytes sha384_digest = 6; // A SHA512 hash to be signed. Must be 64 bytes. bytes sha512_digest = 7; } } message OffloadPrivateKeyOperationResp { // The signed or decrypted output bytes. bytes out_bytes = 1; } message OffloadResumptionKeyOperationReq { enum ResumptionKeyOperation { UNSPECIFIED = 0; ENCRYPT = 1; DECRYPT = 2; } // The operation the resumption key is used for. ResumptionKeyOperation operation = 1; // The bytes to be encrypted or decrypted. bytes in_bytes = 2; } message OffloadResumptionKeyOperationResp { // The encrypted or decrypted bytes. bytes out_bytes = 1; } message ValidatePeerCertificateChainReq { enum VerificationMode { // The default verification mode supported by S2A. UNSPECIFIED = 0; // The SPIFFE verification mode selects the set of trusted certificates to // use for path building based on the SPIFFE trust domain in the peer's leaf // certificate. SPIFFE = 1; // The connect-to-Google verification mode uses the trust bundle for // connecting to Google, e.g. *.mtls.googleapis.com endpoints. CONNECT_TO_GOOGLE = 2; // Internal use only. RESERVED_CUSTOM_VERIFICATION_MODE_3 = 3; // Internal use only. RESERVED_CUSTOM_VERIFICATION_MODE_4 = 4; // Internal use only. RESERVED_CUSTOM_VERIFICATION_MODE_5 = 5; } message ClientPeer { // The certificate chain to be verified. The chain MUST be a list of // DER-encoded certificates, ordered from leaf to root, excluding the root. repeated bytes certificate_chain = 1; } message ServerPeer { // The certificate chain to be verified. The chain MUST be a list of // DER-encoded certificates, ordered from leaf to root, excluding the root. repeated bytes certificate_chain = 1; // The expected hostname of the server. string server_hostname = 2; // The UnrestrictedClientPolicy specified by the user. bytes serialized_unrestricted_client_policy = 3; } // The verification mode that S2A MUST use to validate the peer certificate // chain. VerificationMode mode = 1; oneof peer_oneof { ClientPeer client_peer = 2; ServerPeer server_peer = 3; } } message ValidatePeerCertificateChainResp { enum ValidationResult { UNSPECIFIED = 0; SUCCESS = 1; FAILURE = 2; } // The result of validating the peer certificate chain. ValidationResult validation_result = 1; // The validation details. This field is only populated when the validation // result is NOT SUCCESS. string validation_details = 2; // The S2A context contains information from the peer certificate chain. // // The S2A context MAY be populated even if validation of the peer certificate // chain fails. S2AContext context = 3; } message SessionReq { reserved 1; // The identity corresponding to the TLS configurations that MUST be used for // the TLS handshake. // // If a managed identity already exists, the local identity and authentication // mechanisms are ignored. If a managed identity doesn't exist and the local // identity is not populated, S2A will try to deduce the managed identity to // use from the SNI extension. If that also fails, S2A uses the default // identity (if one exists). Identity local_identity = 7; // The authentication mechanisms that the application wishes to use to // authenticate to S2A, ordered by preference. S2A will always use the first // authentication mechanism that matches the managed identity. repeated AuthenticationMechanism authentication_mechanisms = 2; oneof req_oneof { // Requests the certificate chain and TLS configuration corresponding to the // local identity, which the application MUST use to negotiate the TLS // handshake. GetTlsConfigurationReq get_tls_configuration_req = 3; // Signs or decrypts the input bytes using a private key corresponding to // the local identity in the request. // // WARNING: More than one OffloadPrivateKeyOperationReq may be sent to the // S2Av2 by a server during a TLS 1.2 handshake. OffloadPrivateKeyOperationReq offload_private_key_operation_req = 4; // Encrypts or decrypts the input bytes using a resumption key corresponding // to the local identity in the request. OffloadResumptionKeyOperationReq offload_resumption_key_operation_req = 5; // Verifies the peer's certificate chain using // (a) trust bundles corresponding to the local identity in the request, and // (b) the verification mode in the request. ValidatePeerCertificateChainReq validate_peer_certificate_chain_req = 6; } } message SessionResp { // Status of the session response. // // The status field is populated so that if an error occurs when making an // individual request, then communication with the S2A may continue. If an // error is returned directly (e.g. at the gRPC layer), then it may result // that the bidirectional stream being closed. Status status = 1; oneof resp_oneof { // Contains the certificate chain and TLS configurations corresponding to // the local identity. GetTlsConfigurationResp get_tls_configuration_resp = 2; // Contains the signed or encrypted output bytes using the private key // corresponding to the local identity. OffloadPrivateKeyOperationResp offload_private_key_operation_resp = 3; // Contains the encrypted or decrypted output bytes using the resumption key // corresponding to the local identity. OffloadResumptionKeyOperationResp offload_resumption_key_operation_resp = 4; // Contains the validation result, peer identity and fingerprints of peer // certificates. ValidatePeerCertificateChainResp validate_peer_certificate_chain_resp = 5; } } service S2AService { // SetUpSession is a bidirectional stream used by applications to offload // operations from the TLS handshake. rpc SetUpSession(stream SessionReq) returns (stream SessionResp) {} }