feat(binding): add key update request api

bindings/rust/s2n-tls/Cargo.toml

@@ -11,6 +11,7 @@ license = "Apache-2.0"
 [features]
 default = []
 unstable-fingerprint = ["s2n-tls-sys/unstable-fingerprint"]
+unstable-ktls = ["s2n-tls-sys/unstable-ktls"]
 quic = ["s2n-tls-sys/quic"]
 pq = ["s2n-tls-sys/pq"]
 testing = ["bytes"]

bindings/rust/s2n-tls/src/connection.rs

@@ -36,6 +36,15 @@ macro_rules! static_const_str {
     };
 }
 
+#[non_exhaustive]
+#[derive(Debug, PartialEq)]
+/// s2n-tls only tracks up to u8::MAX (255) key updates. If any of the fields show
+/// 255 updates, then more than 255 updates may have occurred.
+pub struct KeyUpdateCount {
+    pub send_key_updates: u8,
+    pub recv_key_updates: u8,
+}
+
 pub struct Connection {
     connection: NonNull<s2n_connection>,
 }
@@ -267,6 +276,46 @@ impl Connection {
         Ok(self)
     }
 
+    /// Signals the connection to do a key_update at the next possible opportunity.
+    /// Note that the resulting key update message will not be sent until `send` is
+    /// called on the connection.
+    ///
+    /// `peer_request` indicates if a key update should also be requested
+    /// of the peer. When set to `KeyUpdateNotRequested`, then only the sending
+    /// key of the connection will be updated. If set to `KeyUpdateRequested`, then
+    /// the sending key of conn will be updated AND the peer will be requested to
+    /// update their sending key. Note that s2n-tls currently only supports
+    /// `peer_request` being set to `KeyUpdateNotRequested` and will return an error
+    /// if any other value is used.
+    pub fn request_key_update(&mut self, peer_request: PeerKeyUpdate) -> Result<(), Error> {
+        unsafe {
+            s2n_connection_request_key_update(self.connection.as_ptr(), peer_request.into())
+                .into_result()
+        }?;
+        Ok(())
+    }
+
+    /// Reports the number of times sending and receiving keys have been updated.
+    ///
+    /// This only applies to TLS1.3. Earlier versions do not support key updates.
+    #[cfg(feature = "unstable-ktls")]
+    pub fn key_update_counts(&self) -> Result<KeyUpdateCount, Error> {
+        let mut send_key_updates = 0;
+        let mut recv_key_updates = 0;
+        unsafe {
+            s2n_connection_get_key_update_counts(
+                self.connection.as_ptr(),
+                &mut send_key_updates,
+                &mut recv_key_updates,
+            )
+            .into_result()?;
+        }
+        Ok(KeyUpdateCount {
+            send_key_updates,
+            recv_key_updates,
+        })
+    }
+
     /// sets the application protocol preferences on an s2n_connection object.
     ///
     /// protocols is a list in order of preference, with most preferred protocol first, and of

bindings/rust/s2n-tls/src/enums.rs

@@ -177,3 +177,19 @@ impl TryFrom<s2n_tls_hash_algorithm::Type> for HashAlgorithm {
         Ok(version)
     }
 }
+
+#[non_exhaustive]
+#[derive(Debug, PartialEq, Copy, Clone)]
+pub enum PeerKeyUpdate {
+    KeyUpdateNotRequested,
+    KeyUpdatedRequested,
+}
+
+impl From<PeerKeyUpdate> for s2n_peer_key_update::Type {
+    fn from(input: PeerKeyUpdate) -> s2n_peer_key_update::Type {
+        match input {
+            PeerKeyUpdate::KeyUpdateNotRequested => s2n_peer_key_update::KEY_UPDATE_NOT_REQUESTED,
+            PeerKeyUpdate::KeyUpdatedRequested => s2n_peer_key_update::KEY_UPDATE_REQUESTED,
+        }
+    }
+}

bindings/rust/s2n-tls/src/testing/s2n_tls.rs

@@ -892,4 +892,40 @@ mod tests {
 
         Ok(())
     }
+
+    #[cfg(feature = "unstable-ktls")]
+    #[test]
+    fn key_updates() -> Result<(), Error> {
+        use crate::{connection::KeyUpdateCount, enums::PeerKeyUpdate};
+
+        let empty_key_updates = KeyUpdateCount {
+            recv_key_updates: 0,
+            send_key_updates: 0,
+        };
+
+        let pair = tls_pair(build_config(&security::DEFAULT_TLS13)?);
+        let mut pair = poll_tls_pair(pair);
+
+        // there haven't been any key updates at the start of the connection
+        let client_updates = pair.client.0.connection.as_ref().key_update_counts()?;
+        assert_eq!(client_updates, empty_key_updates);
+        let server_updates = pair.server.0.connection.as_ref().key_update_counts()?;
+        assert_eq!(server_updates, empty_key_updates);
+
+        pair.server
+            .0
+            .connection
+            .as_mut()
+            .request_key_update(PeerKeyUpdate::KeyUpdateNotRequested)?;
+        assert!(pair.poll_send(Mode::Server, &[0]).is_ready());
+
+        // the server send key has been updated
+        let client_updates = pair.client.0.connection.as_ref().key_update_counts()?;
+        assert_eq!(client_updates, empty_key_updates);
+        let server_updates = pair.server.0.connection.as_ref().key_update_counts()?;
+        assert_eq!(server_updates.recv_key_updates, 0);
+        assert_eq!(server_updates.send_key_updates, 1);
+
+        Ok(())
+    }
 }