package s2a.proto.v2

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc SetUpSession (stream SessionReq, stream SessionResp)

  s2a.proto:376

  SetUpSession is a bidirectional stream used by applications to offload operations from the TLS handshake.

  message SessionReq

  s2a.proto:304

  • optional Identity local_identity = 7

    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).

  • repeated AuthenticationMechanism authentication_mechanisms = 2

    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.

  • oneof req_oneof

    • GetTlsConfigurationReq get_tls_configuration_req = 3

      Requests the certificate chain and TLS configuration corresponding to the local identity, which the application MUST use to negotiate the TLS handshake.

    • OffloadPrivateKeyOperationReq offload_private_key_operation_req = 4

      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.

    • OffloadResumptionKeyOperationReq offload_resumption_key_operation_req = 5

      Encrypts or decrypts the input bytes using a resumption key corresponding to the local identity in the request.

    • ValidatePeerCertificateChainReq validate_peer_certificate_chain_req = 6

      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.

  message SessionResp

  s2a.proto:345

  • optional Status status = 1

    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.

  • oneof resp_oneof

    • GetTlsConfigurationResp get_tls_configuration_resp = 2

      Contains the certificate chain and TLS configurations corresponding to the local identity.

    • OffloadPrivateKeyOperationResp offload_private_key_operation_resp = 3

      Contains the signed or encrypted output bytes using the private key corresponding to the local identity.

    • OffloadResumptionKeyOperationResp offload_resumption_key_operation_resp = 4

      Contains the encrypted or decrypted output bytes using the resumption key corresponding to the local identity.

    • ValidatePeerCertificateChainResp validate_peer_certificate_chain_resp = 5

      Contains the validation result, peer identity and fingerprints of peer certificates.

Used in: GetTlsConfigurationResp.ClientTlsConfiguration, GetTlsConfigurationResp.ServerTlsConfiguration

• bool enable_alpn_negotiation = 1

  If true, the application MUST perform ALPN negotiation.

• repeated AlpnProtocol alpn_protocols = 2

  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.

The ALPN protocols that the application can negotiate during a TLS handshake.

Used in: AlpnPolicy

• ALPN_PROTOCOL_UNSPECIFIED = 0

• ALPN_PROTOCOL_GRPC = 1

• ALPN_PROTOCOL_HTTP2 = 2

• ALPN_PROTOCOL_HTTP1_1 = 3

Used in: SessionReq

• optional Identity identity = 3

  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.

• oneof mechanism_oneof

  • string token = 2

    A token that the application uses to authenticate itself to S2A.

The TLS 1.0-1.2 ciphersuites that the application can negotiate when using S2A.

Used in: GetTlsConfigurationResp.ClientTlsConfiguration, GetTlsConfigurationResp.ServerTlsConfiguration

• CIPHERSUITE_UNSPECIFIED = 0

• CIPHERSUITE_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 = 1

• CIPHERSUITE_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 = 2

• CIPHERSUITE_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 = 3

• CIPHERSUITE_ECDHE_RSA_WITH_AES_128_GCM_SHA256 = 4

• CIPHERSUITE_ECDHE_RSA_WITH_AES_256_GCM_SHA384 = 5

• CIPHERSUITE_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 = 6

The side in the TLS connection.

Used in: GetTlsConfigurationReq

• CONNECTION_SIDE_UNSPECIFIED = 0

• CONNECTION_SIDE_CLIENT = 1

• CONNECTION_SIDE_SERVER = 2

Used in: SessionReq

• ConnectionSide connection_side = 1

  The role of the application in the TLS connection.

• string sni = 2

  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.

Used in: SessionResp

• oneof tls_configuration

  • GetTlsConfigurationResp.ClientTlsConfiguration client_tls_configuration = 1

  • GetTlsConfigurationResp.ServerTlsConfiguration server_tls_configuration = 2

Next ID: 8

Used in: GetTlsConfigurationResp

• repeated string certificate_chain = 1

  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.

• TLSVersion min_tls_version = 2

  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 max_tls_version = 3

  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.

• repeated Ciphersuite ciphersuites = 6

  The ordered list of TLS 1.0-1.2 ciphersuites that the client MAY offer to negotiate in the TLS handshake.

• optional AlpnPolicy alpn_policy = 7

  The policy that dictates how the client negotiates ALPN during the TLS handshake.

Next ID: 12

Used in: GetTlsConfigurationResp

• repeated string certificate_chain = 1

  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.

• TLSVersion min_tls_version = 2

  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 max_tls_version = 3

  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.

• repeated Ciphersuite ciphersuites = 10

  The ordered list of TLS 1.0-1.2 ciphersuites that the server MAY offer to negotiate in the TLS handshake.

• bool tls_resumption_enabled = 6

  Whether to enable TLS resumption.

• ServerTlsConfiguration.RequestClientCertificate request_client_certificate = 7

  Whether the server MUST request a client certificate (i.e. to negotiate TLS vs. mTLS).

• uint32 max_overhead_of_ticket_aead = 9

  Returns the maximum number of extra bytes that |OffloadResumptionKeyOperation| can add to the number of unencrypted bytes to form the encrypted bytes.

• optional AlpnPolicy alpn_policy = 11

  The policy that dictates how the server negotiates ALPN during the TLS handshake.

Used in: ServerTlsConfiguration

• 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

Used in: AuthenticationMechanism, S2AContext, SessionReq

• oneof identity_oneof

  • string spiffe_id = 1

    The SPIFFE ID of a connection endpoint.

  • string hostname = 2

    The hostname of a connection endpoint.

  • string uid = 4

    The UID of a connection endpoint.

  • string username = 5

    The username of a connection endpoint.

  • string gcp_id = 6

    The GCP ID of a connection endpoint.

• map<string, string> attributes = 3

  Additional identity-specific attributes.

Used in: SessionReq

• OffloadPrivateKeyOperationReq.PrivateKeyOperation operation = 1

  The operation the private key is used for.

• SignatureAlgorithm signature_algorithm = 2

  The signature algorithm to be used for signing operations.

• oneof in_bytes

  The input bytes to be signed or decrypted.

  • bytes raw_bytes = 4

    Raw bytes to be hashed and signed, or decrypted.

  • bytes sha256_digest = 5

    A SHA256 hash to be signed. Must be 32 bytes.

  • bytes sha384_digest = 6

    A SHA384 hash to be signed. Must be 48 bytes.

  • bytes sha512_digest = 7

    A SHA512 hash to be signed. Must be 64 bytes.

Used in: OffloadPrivateKeyOperationReq

• UNSPECIFIED = 0

• SIGN = 1

  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.

• DECRYPT = 2

  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.

Used in: SessionResp

• bytes out_bytes = 1

  The signed or decrypted output bytes.

Used in: SessionReq

• OffloadResumptionKeyOperationReq.ResumptionKeyOperation operation = 1

  The operation the resumption key is used for.

• bytes in_bytes = 2

  The bytes to be encrypted or decrypted.

Used in: OffloadResumptionKeyOperationReq

• UNSPECIFIED = 0

• ENCRYPT = 1

• DECRYPT = 2

Used in: SessionResp

• bytes out_bytes = 1

  The encrypted or decrypted bytes.

Used in: ValidatePeerCertificateChainResp

• string leaf_cert_spiffe_id = 1

  The SPIFFE ID from the peer leaf certificate, if present. This field is only populated if the leaf certificate is a valid SPIFFE SVID; in particular, there is a unique URI SAN and this URI SAN is a valid SPIFFE ID.

• repeated string leaf_cert_uris = 2

  The URIs that are present in the SubjectAltName extension of the peer leaf certificate. Note that the extracted URIs are not validated and may not be properly formatted.

• repeated string leaf_cert_dnsnames = 3

  The DNSNames that are present in the SubjectAltName extension of the peer leaf certificate.

• repeated string peer_certificate_chain_fingerprints = 4

  The (ordered) list of fingerprints in the certificate chain used to verify the given leaf certificate. The order MUST be from leaf certificate fingerprint to root certificate fingerprint. A fingerprint is the base-64 encoding of the SHA256 hash of the DER-encoding of a certificate. The list MAY be populated even if the peer certificate chain was NOT validated successfully.

• optional Identity local_identity = 9

  The local identity used during session setup.

• bytes local_leaf_cert_fingerprint = 6

  The SHA256 hash of the DER-encoding of the local leaf certificate used in the handshake.

Used in: OffloadPrivateKeyOperationReq

• S2A_SSL_SIGN_UNSPECIFIED = 0

• S2A_SSL_SIGN_RSA_PKCS1_SHA256 = 1

  RSA Public-Key Cryptography Standards #1.

• S2A_SSL_SIGN_RSA_PKCS1_SHA384 = 2

• S2A_SSL_SIGN_RSA_PKCS1_SHA512 = 3

• S2A_SSL_SIGN_ECDSA_SECP256R1_SHA256 = 4

  ECDSA.

• S2A_SSL_SIGN_ECDSA_SECP384R1_SHA384 = 5

• S2A_SSL_SIGN_ECDSA_SECP521R1_SHA512 = 6

• S2A_SSL_SIGN_RSA_PSS_RSAE_SHA256 = 7

  RSA Probabilistic Signature Scheme.

• S2A_SSL_SIGN_RSA_PSS_RSAE_SHA384 = 8

• S2A_SSL_SIGN_RSA_PSS_RSAE_SHA512 = 9

• S2A_SSL_SIGN_ED25519 = 10

  ED25519.

Used in: SessionResp

• uint32 code = 1

  The status code that is specific to the application and the implementation of S2A, e.g., gRPC status code.

• string details = 2

  The status details.

The TLS versions supported by S2A's handshaker module.

Used in: GetTlsConfigurationResp.ClientTlsConfiguration, GetTlsConfigurationResp.ServerTlsConfiguration

• TLS_VERSION_UNSPECIFIED = 0

• TLS_VERSION_1_0 = 1

• TLS_VERSION_1_1 = 2

• TLS_VERSION_1_2 = 3

• TLS_VERSION_1_3 = 4

Used in: SessionReq

• ValidatePeerCertificateChainReq.VerificationMode mode = 1

  The verification mode that S2A MUST use to validate the peer certificate chain.

• oneof peer_oneof

  • ValidatePeerCertificateChainReq.ClientPeer client_peer = 2

  • ValidatePeerCertificateChainReq.ServerPeer server_peer = 3

Used in: ValidatePeerCertificateChainReq

• repeated bytes certificate_chain = 1

  The certificate chain to be verified. The chain MUST be a list of DER-encoded certificates, ordered from leaf to root, excluding the root.

Used in: ValidatePeerCertificateChainReq

• repeated bytes certificate_chain = 1

  The certificate chain to be verified. The chain MUST be a list of DER-encoded certificates, ordered from leaf to root, excluding the root.

• string server_hostname = 2

  The expected hostname of the server.

• bytes serialized_unrestricted_client_policy = 3

  The UnrestrictedClientPolicy specified by the user.

Used in: ValidatePeerCertificateChainReq

• UNSPECIFIED = 0

  The default verification mode supported by S2A.

• SPIFFE = 1

  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.

• CONNECT_TO_GOOGLE = 2

  The connect-to-Google verification mode uses the trust bundle for connecting to Google, e.g. *.mtls.googleapis.com endpoints.

• RESERVED_CUSTOM_VERIFICATION_MODE_3 = 3

  Internal use only.

• RESERVED_CUSTOM_VERIFICATION_MODE_4 = 4

  Internal use only.

• RESERVED_CUSTOM_VERIFICATION_MODE_5 = 5

  Internal use only.

• RESERVED_CUSTOM_VERIFICATION_MODE_6 = 6

  Internal use only.

• RESERVED_CUSTOM_VERIFICATION_MODE_7 = 7

  Internal use only.

Used in: SessionResp

• ValidatePeerCertificateChainResp.ValidationResult validation_result = 1

  The result of validating the peer certificate chain.

• string validation_details = 2

  The validation details. This field is only populated when the validation result is NOT SUCCESS.

• optional S2AContext context = 3

  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.

Used in: ValidatePeerCertificateChainResp

• UNSPECIFIED = 0

• SUCCESS = 1

• FAILURE = 2