API Design

[ShadowJonathan]

This is a draft for the API design I currently have in mind, i'm currently thinking of 5 main objects;

• DClientAgent, a handshaker state machine that performs in much the same way rustls::ClientCommon does, my current idea is as follows;

  • An application supplies it with datagram packets, then polls it, and in a black-box fashion, it'll only give one of three answers;
  • "Await until this deadline, then poll me again"
  • "I am ready to write to the socket"
  • "I have encountered an error" (todo: how would handling an alert + error look like? "write this pls", poll(), "i got an error", in quick succession, writing the fatal but buffering the error until next call?)
  • This object handles retransmission timers internally
  • When complete, the poll() will return with "success, here's your connection object"

• DClientSession, a IO object for which the application can supply datagram packets, and supply it chunks of bytes it want to encode.

  • This will likely function exactly the same as rustls::ClientCommon, only that it supplies exact datagrams, and no streams of data.
  • "function exactly the same" wrt write_tls, read_tls, wants_write, etc. I don't believe wants_read is really needed, as all records are supposed to fit into one datagram, though i'll have to consult the RFC for that again.
  • The output will be datagram-based, so again, possibly no Read + Write traits

• DServerListener, an object that handles all incoming "leftover" packets that do not belong to a connection, handles ClientHellos with HelloVerifyRequests, verifies ClientHellos with cookies, and if successful, then produces a handshaker object for the application to continue verifying with.

  • This object needs some sort of "cookie generator", which needs to be cryptographically secure and hard to guess, else DoS amplification attacks can be performed with this listener.

• DServerAgent, pretty much the same as DClientAgent, only on the different side of the transaction.

• DServerSession, ditto.

---

These objects basically give an entirely hands-off buffer-based black-box approach to DTLS connection handling, with the application being who needs to handle underlying UdpSocket multiplexing, routing, buffering, and more.

This is to ensure this encryption layer can work over any kind of channel that is unreliable, unordered, but framed, this last guarantee is the most important one, and i'm not sure how to encode that into the IO. Rust doesn't give standard traits or libraries that "understand" a connections "framed-ness". Though luckily objects like UdpSocket don't provide Write + Read at all, and instead require manual polling of the recv and send functions, so i think it's plenty okay to leave that functionality to a wrapping connection manager (such as tokio-rustls is to rustls)

[ShadowJonathan]

The handshakers would probably want to decrease their MTU every time it retransmits, and store this suggestion value for the connection to use.

Though, i'll also want to make that MTU variable available to be altered on the connection objects, if the application discovers it can send bigger datagram packets then the connection objects are currently doing.

Also, i'd like a better name for the connection objects, "connection" is probably the wrong word, maybe "session"?

[ShadowJonathan]

Also, i'd like a better name for the connection objects, "connection" is probably the wrong word, maybe "session"?

Draft 43 of DTLS v1.3 seems to define some terminology, I think it's best to have the names follow from these terms.