docs: adjust docs, misc

Author: cxw620

ktls-util/src/client.rs

@@ -36,32 +36,32 @@ impl KtlsConnector {
     ///
     /// [`SetupError`]. This may contain the original socket if the setup failed
     /// and the caller can fallback to normal TLS connector implementation.
-    pub async fn try_connect<IO>(
+    pub async fn try_connect<S>(
         &self,
-        socket: IO,
+        socket: S,
         server_name: ServerName<'static>,
-    ) -> Result<KtlsStream<IO>, SetupError<IO>>
+    ) -> Result<KtlsStream<S>, SetupError<S>>
     where
-        IO: AsyncRead + AsyncWrite + AsFd + Unpin,
+        S: AsyncRead + AsyncWrite + AsFd + Unpin,
     {
         let socket = setup_ulp(socket)?;
 
         self.internal_try_connect(socket, server_name)
             .await
             .map_err(|error| SetupError {
                 error: io::Error::other(error),
-                stream: None,
+                socket: None,
             })
     }
 
     // `rustls` has poor support for async/await...
-    async fn internal_try_connect<IO>(
+    async fn internal_try_connect<S>(
         &self,
-        mut socket: IO,
+        mut socket: S,
         server_name: ServerName<'static>,
-    ) -> Result<KtlsStream<IO>, ktls::Error>
+    ) -> Result<KtlsStream<S>, ktls::Error>
     where
-        IO: AsyncRead + AsyncWrite + AsFd + Unpin,
+        S: AsyncRead + AsyncWrite + AsFd + Unpin,
     {
         let mut conn = UnbufferedClientConnection::new(self.config.clone(), server_name)
             .map_err(ktls::Error::Config)?;

ktls-util/src/lib.rs

@@ -28,9 +28,9 @@ pub mod client;
 pub mod server;
 pub mod suites;
 
-pub(crate) async fn read_record<IO>(socket: &mut IO, incoming: &mut Vec<u8>) -> io::Result<()>
+pub(crate) async fn read_record<S>(socket: &mut S, incoming: &mut Vec<u8>) -> io::Result<()>
 where
-    IO: AsyncRead + Unpin,
+    S: AsyncRead + Unpin,
 {
     const RECORD_HDR_SIZE: usize = 5;
 

ktls-util/src/server.rs

@@ -35,23 +35,23 @@ impl KtlsAcceptor {
     ///
     /// [`SetupError`]. This may contain the original socket if the setup failed
     /// and the caller can fallback to normal TLS acceptor implementation.
-    pub async fn try_accept<IO>(&self, socket: IO) -> Result<KtlsStream<IO>, SetupError<IO>>
+    pub async fn try_accept<S>(&self, socket: S) -> Result<KtlsStream<S>, SetupError<S>>
     where
-        IO: AsyncRead + AsyncWrite + AsFd + Unpin,
+        S: AsyncRead + AsyncWrite + AsFd + Unpin,
     {
         let socket = setup_ulp(socket)?;
 
         self.internal_try_accept(socket)
             .await
             .map_err(|error| SetupError {
                 error: io::Error::other(error),
-                stream: None,
+                socket: None,
             })
     }
 
-    async fn internal_try_accept<IO>(&self, mut socket: IO) -> Result<KtlsStream<IO>, ktls::Error>
+    async fn internal_try_accept<S>(&self, mut socket: S) -> Result<KtlsStream<S>, ktls::Error>
     where
-        IO: AsyncWrite + AsyncRead + AsFd + Unpin,
+        S: AsyncWrite + AsyncRead + AsFd + Unpin,
     {
         let mut conn =
             UnbufferedServerConnection::new(self.config.clone()).map_err(ktls::Error::Config)?;

ktls-util/src/suites.rs

@@ -4,7 +4,7 @@ use std::collections::HashSet;
 use std::io;
 use std::net::{TcpListener, TcpStream};
 
-use ktls::setup::{SetupError, TlsCryptoInfoTx};
+use ktls::setup::{setup_ulp, SetupError, TlsCryptoInfoTx};
 use rustls::{CipherSuite, SupportedCipherSuite, SupportedProtocolVersion};
 
 #[derive(Debug, Clone)]
@@ -17,17 +17,22 @@ pub struct CompatibleCipherSuites {
 }
 
 impl CompatibleCipherSuites {
-    /// Probes the current kernel for kTLS cipher suite compatibility.
+    /// Probes the current Linux kernel for kTLS cipher suite compatibility.
     ///
-    /// - If the current kernel does not support kTLS at all, returns None.
-    /// - Otherwise, returns a `CompatibleCipherSuites` instance containing the
-    ///   supported cipher suites and protocol versions.
+    /// Returns `None` if the kernel does not support kTLS, otherwise returns
+    /// a `CompatibleCipherSuites` containing supported cipher suites and
+    /// protocol versions.
     ///
-    /// The caller may cache the result of this function.
+    /// # Notes
+    ///
+    /// - The caller may enable feature `rustls/tls12` to include TLS 1.2
+    ///   support, or the protocol versions may be empty if only TLS 1.2 is
+    ///   supported by current Linux kernel.
+    /// - The caller may cache the result, as probing is expensive.
     ///
     /// ## Errors
     ///
-    /// If an I/O error occurs while probing, an `io::Error` is returned.
+    /// [`io::Error`].
     pub fn probe() -> io::Result<Option<Self>> {
         let listener = TcpListener::bind("127.0.0.0:0")?;
 
@@ -40,10 +45,10 @@ impl CompatibleCipherSuites {
 
         macro_rules! test_param {
             ($method:ident, $data:ident, $version:expr, $cipher_type:expr) => {{
-                let stream = match ktls::setup::setup_ulp(TcpStream::connect(local_addr)?) {
+                let stream = match setup_ulp(TcpStream::connect(local_addr)?) {
                     Ok(stream) => stream,
                     Err(SetupError {
-                        stream: Some(_), ..
+                        socket: Some(_), ..
                     }) => {
                         // kTLS is not supported
                         return Ok(None);
@@ -147,7 +152,8 @@ impl CompatibleCipherSuites {
                 (true, true) => rustls::DEFAULT_VERSIONS,
                 // The first element is TLS 1.3
                 (false, true) => &rustls::DEFAULT_VERSIONS[..1],
-                // The first element is TLS 1.2 (maybe, but empty slice is OK)
+                // The first element is TLS 1.2 (maybe, but empty slice is OK, let the caller handle
+                // it)
                 (true, false) => &rustls::DEFAULT_VERSIONS[1..],
                 // No supported versions
                 (false, false) => return Ok(None),
@@ -156,9 +162,9 @@ impl CompatibleCipherSuites {
     }
 
     /// Filters the provided cipher suites list in place, removing suites
-    /// incompatible with kTLS on the current kernel.
+    /// which is incompatible.
     ///
-    /// # Examples
+    /// ## Examples
     ///
     /// ```no_run
     /// use std::sync::Arc;

ktls/examples/common/client.rs

@@ -1,3 +1,5 @@
+#![allow(dead_code)]
+
 use std::sync::Arc;
 
 use rustls::client::danger::{HandshakeSignatureValid, ServerCertVerified, ServerCertVerifier};

ktls/examples/common/mod.rs

@@ -1,4 +1,2 @@
-#![allow(dead_code)]
-
 pub mod client;
 pub mod server;

ktls/examples/common/server.rs

@@ -1,5 +1,7 @@
 //! Example: TLS server using `ktls`.
 
+#![allow(dead_code)]
+
 use std::io;
 use std::sync::Arc;
 

ktls/src/lib.rs

@@ -30,3 +30,4 @@ pub mod setup;
 pub mod stream;
 
 pub use error::Error;
+pub use stream::KtlsStream;

ktls/src/setup/tls.rs

@@ -20,8 +20,8 @@ use crate::error::{Error, InvalidCryptoInfo};
 ///
 /// * Invalid crypto materials.
 /// * Syscall error.
-pub fn setup_tls_params<IO: AsFd>(
-    socket: &IO,
+pub fn setup_tls_params<S: AsFd>(
+    socket: &S,
     cipher_suite: SupportedCipherSuite,
     secrets: ExtractedSecrets,
 ) -> Result<(), Error> {
@@ -41,8 +41,8 @@ pub fn setup_tls_params<IO: AsFd>(
 /// ## Errors
 ///
 /// See [`setup_tls_params`].
-pub fn setup_tls_params_tx<IO: AsFd>(
-    socket: &IO,
+pub fn setup_tls_params_tx<S: AsFd>(
+    socket: &S,
     cipher_suite: SupportedCipherSuite,
     (seq, secrets): (u64, ConnectionTrafficSecrets),
 ) -> Result<(), Error> {
@@ -61,8 +61,8 @@ pub fn setup_tls_params_tx<IO: AsFd>(
 /// ## Errors
 ///
 /// See [`setup_tls_params`].
-pub fn setup_tls_params_rx<IO: AsFd>(
-    socket: &IO,
+pub fn setup_tls_params_rx<S: AsFd>(
+    socket: &S,
     cipher_suite: SupportedCipherSuite,
     (seq, secrets): (u64, ConnectionTrafficSecrets),
 ) -> Result<(), Error> {

ktls/src/setup/ulp.rs

@@ -18,16 +18,16 @@ use nix::sys::socket::{setsockopt, sockopt};
 /// If the error is caused by the system not supporting kTLS, such as kernel
 /// module `tls` not being enabled or the kernel version being too old, will
 /// have the original socket returned, see [`SetupError::stream`].
-pub fn setup_ulp<IO: AsFd>(socket: IO) -> Result<IO, SetupError<IO>> {
+pub fn setup_ulp<S: AsFd>(socket: S) -> Result<S, SetupError<S>> {
     match setsockopt(&socket, sockopt::TcpUlp::default(), b"tls") {
         Ok(()) => Ok(socket),
         Err(err) if err == Errno::ENOENT => Err(SetupError {
             error: io::Error::from(err),
-            stream: Some(socket),
+            socket: Some(socket),
         }),
         Err(err) => Err(SetupError {
             error: io::Error::from(err),
-            stream: None,
+            socket: None,
         }),
     }
 }
@@ -36,16 +36,16 @@ pub fn setup_ulp<IO: AsFd>(socket: IO) -> Result<IO, SetupError<IO>> {
 #[derive(thiserror::Error)]
 #[error("{error}")]
 /// An error that occurred while configuring the ULP.
-pub struct SetupError<IO> {
+pub struct SetupError<S> {
     #[source]
     /// The I/O error that occurred while configuring the ULP.
     pub error: io::Error,
 
-    /// The original I/O stream.
-    pub stream: Option<IO>,
+    /// The original I/O socket.
+    pub socket: Option<S>,
 }
 
-impl<IO> fmt::Debug for SetupError<IO> {
+impl<S> fmt::Debug for SetupError<S> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         self.error.fmt(f)
     }