package s2a.proto

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc SetUpSession (stream SessionReq, stream SessionResp)

  s2a.proto:266

  S2A service accepts a stream of session setup requests and returns a stream of session setup responses. The client of this service is expected to send exactly one client_start or server_start message followed by at least one next message. Applications running TLS clients can send requests with resumption_ticket messages only after the session is successfully set up. Every time S2A client sends a request, this service sends a response. However, clients do not have to wait for service response before sending the next request.

  message SessionReq

  s2a.proto:132

  • oneof req_oneof

    • ClientSessionStartReq client_start = 1

      The client session setup request message.

    • ServerSessionStartReq server_start = 2

      The server session setup request message.

    • SessionNextReq next = 3

      The next session setup message request message.

    • ResumptionTicketReq resumption_ticket = 4

      The resumption ticket that is received from the server. This message is only accepted by S2A if it is running as a client and if it is received after session setup is complete. If S2A is running as a server and it receives this message, the session is terminated.

  • repeated AuthenticationMechanism auth_mechanisms = 5

    (Optional) The authentication mechanisms that the client wishes to use to authenticate to the S2A, ordered by preference. The S2A will always use the first authentication mechanism that appears in the list and is supported by the S2A.

  message SessionResp

  s2a.proto:225

  • optional Identity local_identity = 1

    The local identity used during session setup. This could be: - The local identity that the client specifies in ClientSessionStartReq. - One of the local identities that the server specifies in ServerSessionStartReq. - If neither client or server specifies local identities, the S2A picks the default one. In this case, this field will contain that identity. If the SessionResult is populated, then this must coincide with the local identity specified in the SessionResult; otherwise, the handshake must fail.

  • bytes out_frames = 2

    The byte representation of the frames that should be sent to the peer. May be empty if nothing needs to be sent to the peer or if in_bytes in the SessionReq is incomplete. All bytes in a non-empty out_frames must be sent to the peer even if the session setup status is not OK as these frames may contain appropriate alerts.

  • uint32 bytes_consumed = 3

    Number of bytes in the in_bytes field that are consumed by S2A. It is possible that part of in_bytes is unrelated to the session setup process.

  • optional SessionResult result = 4

    This is set if the session is successfully set up. out_frames may still be set to frames that needs to be forwarded to the peer.

  • optional SessionStatus status = 5

    Status of session setup at the current stage.

Used in: SessionReq

• optional Identity identity = 1

  (Optional) Application 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, session setup fails.

• oneof mechanism_oneof

  • string token = 2

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

The ciphersuites supported by S2A. The name determines the confidentiality, and authentication ciphers as well as the hash algorithm used for PRF in TLS 1.2 or HKDF in TLS 1.3. Thus, the components of the name are: - AEAD -- for encryption and authentication, e.g., AES_128_GCM. - Hash algorithm -- used in PRF or HKDF, e.g., SHA256.

Used in: ClientSessionStartReq, S2AContext, ServerSessionStartReq, SessionState

• AES_128_GCM_SHA256 = 0

• AES_256_GCM_SHA384 = 1

• CHACHA20_POLY1305_SHA256 = 2

Used in: SessionReq

• repeated string application_protocols = 1

  The application protocols supported by the client, e.g., "grpc".

• TLSVersion min_tls_version = 2

  (Optional) The minimum TLS version number that the S2A's handshaker module will use to set up the session. If this field is not provided, S2A will use the minimum version it supports.

• TLSVersion max_tls_version = 3

  (Optional) The maximum TLS version number that the S2A's handshaker module will use to set up the session. If this field is not provided, S2A will use the maximum version it supports.

• repeated Ciphersuite tls_ciphersuites = 4

  The TLS ciphersuites that the client is willing to support.

• repeated Identity target_identities = 5

  (Optional) Describes which server identities are acceptable by the client. If target identities are provided and none of them matches the peer identity of the server, session setup fails.

• optional Identity local_identity = 6

  (Optional) Application may specify a local identity. Otherwise, S2A chooses the default local identity. If the default identity cannot be determined, session setup fails.

• string target_name = 7

  The target name that is used by S2A to configure SNI in the TLS handshake. It is also used to perform server authorization check if avaiable. This check is intended to verify that the peer authenticated identity is authorized to run a service with the target name. This field MUST only contain the host portion of the server address. It MUST not contain the scheme or the port number. For example, if the server address is dns://www.example.com:443, the value of this field should be set to www.example.com.

Used in: AuthenticationMechanism, ClientSessionStartReq, ResumptionTicketReq, S2AContext, ServerSessionStartReq, SessionResp, SessionResult

• 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

• repeated bytes in_bytes = 1

  The byte representation of a NewSessionTicket message received from the server.

• uint64 connection_id = 2

  A connection identifier that was created and sent by S2A at the end of a handshake.

• optional Identity local_identity = 3

  The local identity that was used by S2A during session setup and included in |SessionResult|.

• string application_protocol = 1

  The application protocol negotiated for this connection, e.g., 'grpc'.

• TLSVersion tls_version = 2

  The TLS version number that the S2A's handshaker module used to set up the session.

• Ciphersuite ciphersuite = 3

  The TLS ciphersuite negotiated by the S2A's handshaker module.

• optional Identity peer_identity = 4

  The authenticated identity of the peer.

• optional Identity local_identity = 5

  The local identity used during session setup. This could be: - The local identity that the client specifies in ClientSessionStartReq. - One of the local identities that the server specifies in ServerSessionStartReq. - If neither client or server specifies local identities, the S2A picks the default one. In this case, this field will contain that identity.

• bytes peer_cert_fingerprint = 6

  The SHA256 hash of the peer certificate used in the handshake.

• bytes local_cert_fingerprint = 7

  The SHA256 hash of the local certificate used in the handshake.

• bool is_handshake_resumed = 8

  Set to true if a cached session was reused to resume the handshake.

Used in: SessionReq

• repeated string application_protocols = 1

  The application protocols supported by the server, e.g., "grpc".

• TLSVersion min_tls_version = 2

  (Optional) The minimum TLS version number that the S2A's handshaker module will use to set up the session. If this field is not provided, S2A will use the minimum version it supports.

• TLSVersion max_tls_version = 3

  (Optional) The maximum TLS version number that the S2A's handshaker module will use to set up the session. If this field is not provided, S2A will use the maximum version it supports.

• repeated Ciphersuite tls_ciphersuites = 4

  The TLS ciphersuites that the server is willing to support.

• repeated Identity local_identities = 5

  (Optional) A list of local identities supported by the server, if specified. Otherwise, S2A chooses the default local identity. If the default identity cannot be determined, session setup fails.

• bytes in_bytes = 6

  The byte representation of the first handshake message received from the client peer. It is possible that this first message is split into multiple chunks. In this case, the first chunk is sent using this field and the following chunks are sent using the in_bytes field of SessionNextReq Specifically, if the client peer is using S2A, this field contains the bytes in the out_frames field of SessionResp message that the client peer received from its S2A after initiating the handshake.

Used in: SessionReq

• bytes in_bytes = 1

  The byte representation of session setup, i.e., handshake messages. Specifically: - All handshake messages sent from the server to the client. - All, except for the first, handshake messages sent from the client to the server. Note that the first message is communicated to S2A using the in_bytes field of ServerSessionStartReq. If the peer is using S2A, this field contains the bytes in the out_frames field of SessionResp message that the peer received from its S2A.

Used in: SessionResp

• string application_protocol = 1

  The application protocol negotiated for this session.

• optional SessionState state = 2

  The session state at the end. This state contains all cryptographic material required to initialize the record protocol object.

• optional Identity peer_identity = 4

  The authenticated identity of the peer.

• optional Identity local_identity = 5

  The local identity used during session setup. This could be: - The local identity that the client specifies in ClientSessionStartReq. - One of the local identities that the server specifies in ServerSessionStartReq. - If neither client or server specifies local identities, the S2A picks the default one. In this case, this field will contain that identity.

• bytes local_cert_fingerprint = 6

  The SHA256 hash of the local certificate used in the handshake.

• bytes peer_cert_fingerprint = 7

  The SHA256 hash of the peer certificate used in the handshake.

Used in: SessionResult

• TLSVersion tls_version = 1

  The TLS version number that the S2A's handshaker module used to set up the session.

• Ciphersuite tls_ciphersuite = 2

  The TLS ciphersuite negotiated by the S2A's handshaker module.

• uint64 in_sequence = 3

  The sequence number of the next, incoming, TLS record.

• uint64 out_sequence = 4

  The sequence number of the next, outgoing, TLS record.

• bytes in_key = 5

  The key for the inbound direction.

• bytes out_key = 6

  The key for the outbound direction.

• bytes in_fixed_nonce = 7

  The constant part of the record nonce for the outbound direction.

• bytes out_fixed_nonce = 8

  The constant part of the record nonce for the inbound direction.

• uint64 connection_id = 9

  A connection identifier that can be provided to S2A to perform operations related to this connection. This identifier will be stored by the record protocol, and included in the |ResumptionTicketReq| message that is later sent back to S2A. This field is set only for client-side connections.

• bool is_handshake_resumed = 10

  Set to true if a cached session was reused to do an abbreviated handshake.

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: ClientSessionStartReq, S2AContext, ServerSessionStartReq, SessionState

• TLS1_2 = 0

• TLS1_3 = 1