Class SSL.Connection

Inheritance graph

class SSL.Connection

Description

SSL.Connection keeps the state relevant for a single SSL connection. This includes the Context object (which doesn't change), various buffers, the Session object (reused or created as appropriate), and pending read and write states being negotiated.

Each connection will have two sets of read and write States: The current read and write states used for encryption, and pending read and write states to be taken into use when the current keyexchange handshake is finished.

This object is also responsible for managing incoming and outgoing packets. Outgoing packets are stored in queue objects and sent in priority order.

Note

This class should never be created directly, instead one of the classes that inherits it should be used (ie either ClientConnection or ServerConnection) depending on whether this is to be a client-side or server-side connection. These in turn are typically created by File()->create().

Constant window_size: private constant int SSL.Connection.window_size
Description: Number of passed sequence numbers to keep track of. RFC 4347 section 4.1.2.5: A minimum window size of 32 MUST be supported, but a window size of 64 is preferred and SHOULD be employed as the default. Another window size (larger than the minimum) MAY be chosen by the receiver.

Variable application_protocol: string(8bit)|zero SSL.Connection.application_protocol
Description: Selected ALPN (RFC 7301) protocol (if any).
Note: Note that this is a connection property, and needs to be renegotiated on session resumption.

Variable client_random
Variable server_random: string(8bit)|zero SSL.Connection.client_random
string(8bit)|zero SSL.Connection.server_random
Description: Random cookies, sent and received with the hello-messages.

Variable early_data_accepted_1_3: bool SSL.Connection.early_data_accepted_1_3
Description: TLS 1.3 and later (RFC 8446 section 4.2.10): true once 0-RTT early data has been accepted for this connection -- on the client side, set once the server's EncryptedExtensions acknowledges accepting the data offered via ClientConnection.early_data_sent_1_3 (drives whether HANDSHAKE_end_of_early_data gets sent, RFC 8446 section 4.5); on the server side, set directly by the 0-RTT accept/reject decision in ServerConnection.reply_new_session_1_3() (relaxes got_data()'s normal "no application data during the handshake" check for the early-data records that precede it).

Variable early_data_skip_budget_1_3: protected int SSL.Connection.early_data_skip_budget_1_3
Description: TLS 1.3 and later, server side: remaining ciphertext octets we are willing to discard while skip_undecryptable_early_data_1_3 is set, as a DoS backstop -- initialized from the context's declared max_early_data_size when 0-RTT is declined.

Variable ke: .Cipher.KeyExchange|zero SSL.Connection.ke
Description: The active Cipher.KeyExchange (if any).

Variable key_schedule: KeySchedule|zero SSL.Connection.key_schedule
Description: TLS 1.3 and later: the running key schedule for this connection.
See also: KeySchedule, new_traffic_state()

Variable key_update_count: int(0..) SSL.Connection.key_update_count
Description: TLS 1.3 and later (RFC 9846 section 4.7.3): the number of KeyUpdates we have sent on this connection -- a sending implementation MUST NOT let this exceed 2^48-1. send_key_update() enforces this as a hard backstop (for call paths, such as an explicit caller-driven update_keys(), with no "just don't" option); the graceful path -- not reciprocating a peer's update_requested if doing so would exceed the cap -- is instead in each side's handle_key_update_1_3().

Variable sent: int|zero SSL.Connection.sent
Description: Number of application data bytes sent by us.

Variable sequence_mask: private int SSL.Connection.sequence_mask
Description: Bitmask representing sequence numbers for accepted received packets in the interval [next_seq_num-window_size..next_seq_num-2].
Note: The packet with seqence number next_seq_num-1 is implicitly known to have been received.

Variable skip_undecryptable_early_data_1_3: protected bool SSL.Connection.skip_undecryptable_early_data_1_3
Description: TLS 1.3 and later, server side: set when we've declined to accept 0-RTT (RFC 8446 section 4.2.10) for a ClientHello that offered it, so the client may still have queued early-data records protected under a client_early_traffic_secret we never installed. While this is set, recv_packet() skips (rather than fatally errors on) records that fail to decrypt under current_read_state, per RFC 8446 section 2.3's "skip past" guidance, until either the first successful decrypt (the client's real next flight) or early_data_skip_budget_1_3 is exhausted.

Variable state: ConnectionState SSL.Connection.state
Description: Bitfield with the current connection state.

Method create: SSL.Connection SSL.Connection(Context ctx)
Description: Initialize the connection state.
Parameter ctx: The context for the connection.