Pull Request Dependencies

This is a follow-up to #3795 to close #3778.

TL;DR

If multiple TLS records are coalesced into a single byte blob on the wire, Botan's TLS implementation may experience multiple state changes in a single call to TLS::Channel::received_data(). The ASIO stream must disentangle those state changes for the downstream application to work correctly. We do this by buffering TLS state changes internally and reporting them to the ASIO application step-by-step.

Review Strategy Suggestion

Reviewers should re-iterate the described implementation strategy for the synchronous implementations of handshake() and read_some() first. The asynchronous implementations follow the same principle but are much more involved due to the callback-handle nature of the AsyncOperation idiom.

TLS States (in the ASIO stream wrapper)

Below is a sketch of the states a TLS connection will pass through in the eyes of the TLS ASIO stream wrapper. State transitions are signaled to the downstream application by the behavior of the stream's (asynchronouns) operations. Some state changes must be triggered by the downstream application itself. See the table for an overview of the state transitions.

Link to Excalidraw.com: https://excalidraw.com/#json=_CLKTOpdlnUCnVu0I6_mr,oDT9HxzM9l5BAKTt8F1uqw

Technical Details of the Problem

The ASIO stream wrapper interacts with the underlying TLS implementation via the commonly known APIs: most notably TLS::Channel::received_data() for incoming data from the peer, TLS::Channel::send() for outgoing application data. TLS state changes, decrypted application data from the peer and encrypted data meant to be sent to the peer are communicated via overloads of the TLS::Callbacks class. This happens when the downstream code calls TLS::Channel::received_data() or TLS::Channel::send() (among others).

The core of the problem: A single flight of TLS records received from the peer might cause more than one TLS stream state change (as outlined above). In that case, a single call to ::received_data() (inside the ASIO stream) may make the underlying TLS implementation state "skip" intermediate steps on first glance. The ASIO wrapper needs to be prepared for this and manage those intemediate state changes.

Below is an example, where the ASIO stream acts as a TLS server and a client finishes the handshake, sends some application data and closes the connection in a single flight of bytes (depicted by the yellow boxes). We assume that a single ::(async_)read_some() on the server's socket pulls the entire flight with three coalesced TLS records into the stream's read buffer. The TLS records are: (1) the client's Finished message, (2) some encrypted application data, and (3) a CloseNotify alert. This is perfectly legal behavior of the client.

Link to Excalidraw.com: https://excalidraw.com/#json=oGeAoDoG3RULU52W4fkAi,4Kh9hGhDhO7YmKB8lO3vlw

Note how the ASIO stream wrapper has to disentangle the state changes caused by the single flight of the client's Finished, Application Data and CloseNotify into multiple ASIO function calls and return codes (depicted by the green activation boxes).

The underlying bugfix: Before this rework, the ASIO stream wrapper had processed said coalesced flight without leaving the "Handshake" state. Nevertheless, the (async_)handshake() came back clean but the "End of File" error (that should have been triggered by the peer's CloseNotify) was dropped. A typical downstream application would then simply call (async_)read_some() on the stream to receive data. But this blocked forever -- as the peer had already declared their end of stream.

Implementation Strategy of the State Disentanglement

The TLS implementation provides enough predicate APIs to check for any relevant intermediate states (e.g. is_handshake_finished()). Additionally, the depicted state machine is a directed acyclic graph; therefore, a TLS::Channel that returns true on is_handshake_finished() will always return true for it. Similarly, once a CloseNotify (or any other TLS alert) was seen, there's no going back to a previous state.

Given those invariants, the (asynchronous) operations in the ASIO stream wrapper detect intermediate states simply by checking the relevant predicate methods in the correct order. That way, each operation reacts on the intermediate state changes relevant for them, only.

For instance, (async_)handshake() returns successfully as soon as is_handshake_finished() is true; even if the implementation has already read and decrypted some application data whose TLS record was coalesced with the peer's Finished message. A consecutive call to (async_)read_some() will find said application data in the output buffer and will push that to the downstream application first; even if the implementation has already received the peer's CloseNotify. New data is read from the peer only once neither pending decrypted application data is available nor a protocol error was detected.

The same is true for protocol errors: Stream operations deliberately prioritize their "ultimate goal" over checking for protocol errors. I.e. a handshake operation will return successfully once is_handshake_complete() is true. Even though some coalesced record following the Finished messages might already have resulted in some fatal protocol error. Under the "directed acyclic graph" assumption, the fatal error must have occurred AFTER the successful handshake and is therefore safe to ignore in the handshake operation. Assuming that the application will invoke additional stream operations after the successful handshake, any "retained" fatal protocol alert will surface in due time.

(Maybe) Future Work

We still see two issues with the above-described approach:

1. Currently, the TLS stream does not support one-sided closure (as explicitly allowed in TLS 1.3)
   Once we receive a CloseNotify from the peer, the TLS implementation will, in turn, place a CloseNotify in the output buffer. Hence, a downstream application won't be able to send any more application data through this stream. This is the specified behavior of TLS 1.2, but TLS 1.3 would allow this. We may be able to fix that limitation in a future pull request.
2. TLS 1.3's "Early Data" will complicate the above-described state machine
   This feature allows sending and receiving "early data" when resuming a session, even before the handshake is finished. This complicates the above-described state machine. Also, the current API of the stream wrapper doesn't account for this feature. Supporting "early data" in the stream wrapper might proof difficult, therefore.