Status

This is meant to collect changes to the TLS callbacks (i.e. user-facing API changes). Currently, it is based on master where all client-side TLS 1.3 feature branches are merged. Changes required for the server implementation are additionally cherry-picked here. Note that this builds on the ideas outlined here.

Callbacks that need attention

Here is a collection of insights we had during implementation with suggestions how to tackle the new requirements TLS 1.3 brings to the implementations. Those changes are not yet implemented and might require some discussion.

A word on 0-RTT

We don't have immediate plans to implement it. However, it would certainly have user-facing API implications. I have some hope to be able restrict the changes to additional API, rather than breaking changes, though. I.e. deferring 0-RTT support to after Botan 3.0 is released seems feasible to me.

tls_session_established(const Session&) (mandatory callback)

Currently, applications are required to override that. The TLS 1.2 implementation calls it once a session is established, provides the established session's descriptor and applications must decide whether to persist the session for resumption or discard it. TLS 1.3 got rid of this type of session resumption. Instead it exclusively uses session tickets and allows multiple such tickets per connection (see Callbacks::tls_session_ticket_received).

I don't see a reasonable way to serve this callback with TLS 1.3. @randombit

Ideas:

• replace tls_session_established using a dedicated "session descriptor"
  • deprecate the old callback and keep serving it from TLS 1.2 for now
  • use tls_session_ticket_received for TLS 1.2 session resumption storage decision
    • might mandate a different name (tls_session_should_be_stored ?)
  • new tls_session_established
    • pass a TLS::Summary object, containing info about the new session, e.g
      • protocol version
      • negotiated ciphersuite
      • extended master secret?
      • encrypt-then-MAC?
      • ...
    • would be purely "informational" (callback returns void)
    • might obsolete tls_session_activated() as it carries roughly the same info without the TLS::Summary
• rename tls_session_established() to tls_12_session_established()
  • probably shouldn't be mandatory
    • default implementation always returns true, I guess
  • probably also needs a way to get a connection summary (TLS::Summary as described above)

Side-Note: New TLS::Server API to send new tickets

TLS 1.3 allows for an arbitrary number of tickets at any time after the handshake not just exactly one at the end of the handshake. Hence, we'll need something like TLS::Server::send_new_session_ticket(std::chrono::seconds lifetime) allowing applications to send tickets at their own discretion.

Side-Note: Application-defined Session Ticket content

RFC 8446 4.6.1: "The ticket itself is an opaque label. It MAY be either a database lookup key or a self-encrypted and self-authenticated value." And I think we should allow the application to decide that.

Given the current Session_Manager API, we might extend the sematics of ::save(const Session&) to return the "ticket" where applications could return a lookup handle or the result of Session::encrypt(). Session_Manager::load_from_session_id() already has the right function signature to act as a counter-part. Nevertheless, I'd suggest to rename it to something like restore_from_ticket() for clarity.

tls_dh_agree() / tls_ecdh_agree() along with tls_decode_group_param()

The agreement callbacks receive a public value along with a group specification. They generate a new keypair, perform an agreement and return a tuple of the shared secret and the public value to pass to the peer.

TLS 1.3 encourages clients to offer initial key share values. That allows the server to encrypt most of its first flight. In contrast to TLS 1.2 where the initial key offer is provided by the server in its first flight.

Technically, we could use the above-mentioned callbacks for TLS 1.3 as well. Main difference: The tls_xx_agree() callbacks would be called in clients in a TLS 1.2 session establishment and in servers in a TLS 1.3 session establishment. That might cause confusion.
Additionally, the callbacks are currently not used for the key agreement in the opposite direction. Instead the PK_Key_Agreement is hard-coded.

With KEMs entering the game for PQC-ready TLS we would likely want to add a tls_kem_agree() if we decide to keep those callbacks at all.

If we decide to keep these callbacks, I would suggest to separate ephemeral key generation from the actual agreement. Then both client and server as well as TLS 1.2 and 1.3 could make use of the same callback. To really be useful, one would probably also want to extract the key generation into a callback. Also, we might even abstract from the DH, ECDH (and KEM) differentiation and just have two callbacks, like so:

struct {
  std::vector<uint8_t> public_value;
  std::unique_ptr<Private_Key> private_key;
} tls_generate_ephemeral_key(Group_Params params,
                             bool compressed_public_value,
                             RandomNumberGenerator& rng, ...);

secure_vector<uint8_t>
tls_key_agreement(Group_Params         params,
                  std::vector<uint8_t> peer_public_value,
                  Private_Key& local_private_key, 
                  ...);

Does that sound about right? Somehow, I feel I'm missing the gist of that interface. @randombit

tls_log_error(), ...debug() and debug_bin()

Not actually related to TLS 1.3; though none of these callbacks are used. Now might be a good time to remove them. YAGNI. ;)

Modifications at a Glance

Those modifications are already implemented and merged or are proposed as working implementations in this pull request.

• tls_modify_extensions
  Now has an additional parameter (which_message) that provides context on what handshake message contains the extensions to be modified. The new overload is called for extensible messages introduced in TLS 1.3. The old overload is marked deprecated and is called by the default implementation of the new overload (after filtering out new TLS 1.3 extensible messages to keep its behaviour as close to legacy as possible).

• tls_examine_extensions
  Analogous to the modify callback above.

• tls_session_ticket_received
  Added for TLS 1.3 session tickets. Not touched in this pull request.

• tls_parse_ocsp_response
  Added to influence the OCSP parsing behaviour. Mainly used to better support BoGo tests which send invalid responses that need to be ignored. Not touched in this pull request.

• tls_current_timestamp
  Added to inject user-defined timestamps. Mainly used for deterministic testing (using test vectors from RFC 8448) and certain BoGo tests that define a specific waiting period. Not touched in this pull request.

• tls_peer_closed_connection
  In contrast to older revisions, TLS 1.3 does not mandate an immediate in-kind response when receiving "close_notify". Applications can override this callback to get notified that no more data is to be expected from the peer. With TLS 1.3 they might legally continue sending data and finish with Channel::close() at their own discretion. Returning true from this callback will make TLS 1.3 behave just like 1.2 and reply with a "close_notify" immediately. This is the default behaviour.

• tls_provide_cert_chain_status
  This allows applications to provide stapled OCSP responses for all (or some) intermediate certificates added to the Certificate handshake message. To the best of my understanding, previous versions of TLS allowed stapled OCSP responses for the leaf certificate, only.
  By default, this callback invokes the old tls_provide_cert_status() callback: mimicking the behavior of TLS 1.2 and stapling an OCSP response for the leaf certificate, only.