Expose the Handshake Confirmed state

This is convenient for some client authentication use cases, and for
tests to know when it's safe to force a key update.

quinn-proto/src/connection/mod.rs

@@ -2475,6 +2475,9 @@ impl Connection {
                 }
 
                 self.events.push_back(Event::Connected);
+                if self.side.is_server() {
+                    self.events.push_back(Event::HandshakeConfirmed);
+                }
                 self.state = State::Established;
                 trace!("established");
                 Ok(())
@@ -2884,6 +2887,7 @@ impl Connection {
                         ));
                     }
                     if self.spaces[SpaceId::Handshake].crypto.is_some() {
+                        self.events.push_back(Event::HandshakeConfirmed);
                         self.discard_space(now, SpaceId::Handshake);
                     }
                 }
@@ -3726,6 +3730,8 @@ pub enum Event {
     HandshakeDataReady,
     /// The connection was successfully established
     Connected,
+    /// The handshake was [`confirmed`](https://www.rfc-editor.org/rfc/rfc9001#name-handshake-confirmed)
+    HandshakeConfirmed,
     /// The connection was lost
     ///
     /// Emitted if the peer closes the connection or an error is encountered.

quinn-proto/src/tests/mod.rs

@@ -576,6 +576,10 @@ fn zero_rtt_happypath() {
         pair.server_conn_mut(server_ch).poll(),
         Some(Event::Connected)
     );
+    assert_matches!(
+        pair.server_conn_mut(server_ch).poll(),
+        Some(Event::HandshakeConfirmed)
+    );
     assert_matches!(
         pair.server_conn_mut(server_ch).poll(),
         Some(Event::Stream(StreamEvent::Opened { dir: Dir::Uni }))
@@ -614,6 +618,10 @@ fn zero_rtt_rejection() {
         pair.server_conn_mut(server_ch).poll(),
         Some(Event::Connected)
     );
+    assert_matches!(
+        pair.server_conn_mut(server_ch).poll(),
+        Some(Event::HandshakeConfirmed)
+    );
     assert_matches!(pair.server_conn_mut(server_ch).poll(), None);
     pair.client
         .connections
@@ -655,6 +663,10 @@ fn zero_rtt_rejection() {
         pair.server_conn_mut(server_ch).poll(),
         Some(Event::Connected)
     );
+    assert_matches!(
+        pair.server_conn_mut(server_ch).poll(),
+        Some(Event::HandshakeConfirmed)
+    );
     assert_matches!(pair.server_conn_mut(server_ch).poll(), None);
     let s2 = pair.client_streams(client_ch).open(Dir::Uni).unwrap();
     assert_eq!(s, s2);
@@ -732,6 +744,10 @@ fn test_zero_rtt_incoming_limit<F: FnOnce(&mut ServerConfig)>(configure_server:
         pair.server_conn_mut(server_ch).poll(),
         Some(Event::Connected)
     );
+    assert_matches!(
+        pair.server_conn_mut(server_ch).poll(),
+        Some(Event::HandshakeConfirmed)
+    );
     assert_matches!(
         pair.server_conn_mut(server_ch).poll(),
         Some(Event::Stream(StreamEvent::Opened { dir: Dir::Uni }))

quinn-proto/src/tests/util.rs

@@ -227,6 +227,10 @@ impl Pair {
             self.client_conn_mut(client_ch).poll(),
             Some(Event::Connected { .. })
         );
+        assert_matches!(
+            self.client_conn_mut(client_ch).poll(),
+            Some(Event::HandshakeConfirmed)
+        );
         assert_matches!(
             self.server_conn_mut(server_ch).poll(),
             Some(Event::HandshakeDataReady)
@@ -235,6 +239,10 @@ impl Pair {
             self.server_conn_mut(server_ch).poll(),
             Some(Event::Connected { .. })
         );
+        assert_matches!(
+            self.server_conn_mut(server_ch).poll(),
+            Some(Event::HandshakeConfirmed)
+        );
     }
 
     pub(super) fn client_conn_mut(&mut self, ch: ConnectionHandle) -> &mut Connection {

quinn/src/connection.rs

@@ -349,6 +349,22 @@ impl Connection {
         }
     }
 
+    /// Wait for the connection to enter the [`Handshake
+    /// Confirmed`](https://www.rfc-editor.org/rfc/rfc9001#name-handshake-confirmed) state
+    ///
+    /// For servers, this is the same as the time the connection becomes established. For clients,
+    /// this is the earliest time at which a client can know that the server has accepted client
+    /// authentication, typically one round-trip after the connection becomes established.
+    pub async fn handshake_confirmed(&self) -> Result<(), ConnectionError> {
+        self.0.shared.handshake_confirmed.notified().await;
+        self.0
+            .state
+            .lock("handshake_confirmed")
+            .error
+            .as_ref()
+            .map_or(Ok(()), |err| Err(err.clone()))
+    }
+
     /// Wait for the connection to be closed for any reason
     ///
     /// Despite the return type's name, closed connections are often not an error condition at the
@@ -555,7 +571,8 @@ impl Connection {
         self.0.stable_id()
     }
 
-    // Update traffic keys spontaneously for testing purposes.
+    // Update traffic keys spontaneously for testing purposes. Must not be called before the
+    // handshake is confirmed.
     #[doc(hidden)]
     pub fn force_key_update(&self) {
         self.0
@@ -927,6 +944,7 @@ pub(crate) struct Shared {
     datagram_received: Notify,
     datagrams_unblocked: Notify,
     closed: Notify,
+    handshake_confirmed: Notify,
 }
 
 pub(crate) struct State {
@@ -1084,6 +1102,9 @@ impl State {
                         wake_all(&mut self.stopped);
                     }
                 }
+                HandshakeConfirmed => {
+                    shared.handshake_confirmed.notify_waiters();
+                }
                 ConnectionLost { reason } => {
                     self.terminate(reason, shared);
                 }
@@ -1185,6 +1206,7 @@ impl State {
         shared.stream_incoming[Dir::Bi as usize].notify_waiters();
         shared.datagram_received.notify_waiters();
         shared.datagrams_unblocked.notify_waiters();
+        shared.handshake_confirmed.notify_waiters();
         if let Some(x) = self.on_connected.take() {
             let _ = x.send(false);
         }