fix: clippy warning and misc changes

Author: cxw620

ktls-sys/src/bindings.rs

@@ -5,16 +5,17 @@
 pub struct __IncompleteArrayField<T>(::std::marker::PhantomData<T>, [T; 0]);
 impl<T> __IncompleteArrayField<T> {
     #[inline]
+    #[must_use] 
     pub const fn new() -> Self {
         __IncompleteArrayField(::std::marker::PhantomData, [])
     }
     #[inline]
     pub fn as_ptr(&self) -> *const T {
-        self as *const _ as *const T
+        std::ptr::from_ref(self).cast::<T>()
     }
     #[inline]
     pub fn as_mut_ptr(&mut self) -> *mut T {
-        self as *mut _ as *mut T
+        std::ptr::from_mut(self).cast::<T>()
     }
     #[inline]
     pub unsafe fn as_slice(&self, len: usize) -> &[T] {

ktls/Cargo.toml

@@ -31,10 +31,13 @@ rcgen = { version = "0.14.3" }
 tokio = { version = "1.40", features = ["io-util", "macros", "net", "rt-multi-thread", "signal", "time"] }
 
 [features]
-default = ["tls12", "feature-tokio"]
+default = ["tls12", "async-io-tokio"]
 
 # Enables rustls/tls12
 tls12 = ["rustls/tls12"]
 
-# Implements `AsyncRead` and `AsyncWrite` traits for `KtlsStream`
-feature-tokio = ["dep:tokio"]
+# Expose some low-level APIs
+raw-api = []
+
+# Implements tokio's `AsyncRead` and `AsyncWrite` traits for `KtlsStream`
+async-io-tokio = ["dep:tokio"]

ktls/examples/client.rs

@@ -2,9 +2,9 @@
 
 mod common;
 
-use core::time::Duration;
 use std::error::Error;
 use std::sync::Arc;
+use std::time::Duration;
 
 use rustls::pki_types::ServerName;
 use rustls::ClientConfig;

ktls/src/error.rs

@@ -1,84 +1,67 @@
 //! Error types for the `ktls` crate
 
-use std::{fmt, io};
+use std::io;
 
 use rustls::SupportedCipherSuite;
 
-#[derive(Debug, thiserror::Error)]
 #[non_exhaustive]
+#[derive(Debug, thiserror::Error)]
 /// Unified error type for this crate
 pub enum Error {
     #[error("kTLS is not supported by the current kernel")]
     /// kTLS is not supported by the current kernel.
     Unsupported,
 
     #[error("the negotiated cipher suite [{0:?}] is not supported")]
-    /// The negotiated cipher suite is not supported.
-    UnsupportedCipherSuite(SupportedCipherSuite),
+    /// The negotiated cipher suite is not supported by this crate.
+    UnknownCipherSuite(SupportedCipherSuite),
+
+    #[error(transparent)]
+    /// Invalid crypto material, e.g., wrong size key or IV.
+    InvalidCryptoInfo(#[from] InvalidCryptoInfo),
 
     #[error("failed to extract connection secrets from rustls connection: {0}")]
+    /// Failed to extract connection secrets from rustls connection, e.g., not
+    /// have `config.enable_secret_extraction` set to true
     ExtractSecrets(#[source] rustls::Error),
 
-    #[error("the peer closed the connection before the TLS handshake could be completed")]
-    /// The peer closed the connection before the TLS handshake could be
-    /// completed.
-    ConnectionClosedBeforeHandshakeCompleted,
-
     #[error(transparent)]
     /// General IO error.
     IO(#[from] io::Error),
 
-    #[error("failed to create rustls connection: {0}")]
+    #[error("The peer closed the connection before the TLS handshake could be completed")]
+    /// (Reserved) The peer closed the connection before the TLS handshake could
+    /// be completed.
+    ConnectionClosedBeforeHandshakeCompleted,
+
+    #[error("Failed to create rustls unbuffered connection: {0}")]
+    /// (Reserved)
     Config(#[source] rustls::Error),
 
-    #[error("an error occurred during the handshake: {0}")]
+    #[error("An error occurred during handshake: {0}")]
+    /// (Reserved)
     Handshake(#[source] rustls::Error),
 }
 
 impl From<Error> for io::Error {
     fn from(error: Error) -> Self {
         match error {
             Error::IO(error) => error,
-            _ => io::Error::other(error),
+            _ => Self::other(error),
         }
     }
 }
 
+#[derive(Debug)]
 #[derive(thiserror::Error)]
-#[error("{error}")]
-pub struct TryConnectError<IO, Conn> {
-    #[source]
-    pub error: Error,
-    pub socket: Option<IO>,
-    pub conn: Option<Conn>,
-}
-
-impl<IO, Conn> fmt::Debug for TryConnectError<IO, Conn> {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.debug_struct("TryConnectError")
-            .field("error", &self.error)
-            .finish_non_exhaustive()
-    }
-}
-
-impl<IO, Conn> From<Error> for TryConnectError<IO, Conn> {
-    fn from(error: Error) -> Self {
-        Self {
-            error,
-            socket: None,
-            conn: None,
-        }
-    }
-}
-
-impl<IO, Conn> From<TryConnectError<IO, Conn>> for Error {
-    fn from(value: TryConnectError<IO, Conn>) -> Self {
-        value.error
-    }
-}
+/// Crypto material is invalid, e.g., wrong size key or IV.
+#[non_exhaustive]
+pub enum InvalidCryptoInfo {
+    #[error("Wrong size key")]
+    /// The provided key has an incorrect size (unlikely).
+    WrongSizeKey,
 
-impl<IO, Conn> From<TryConnectError<IO, Conn>> for io::Error {
-    fn from(error: TryConnectError<IO, Conn>) -> Self {
-        error.error.into()
-    }
+    #[error("Wrong size iv")]
+    /// The provided IV has an incorrect size (unlikely).
+    WrongSizeIv,
 }

ktls/src/ffi.rs

@@ -2,7 +2,7 @@
 
 use std::ffi::c_void;
 use std::os::fd::RawFd;
-use std::{io, mem};
+use std::{io, mem, ptr};
 
 // Yes, really. cmsg components are aligned to [libc::c_long]
 pub(crate) struct Cmsg<const N: usize> {
@@ -15,9 +15,8 @@ impl<const N: usize> Cmsg<N> {
     pub(crate) fn new(level: i32, typ: i32, data: [u8; N]) -> Self {
         Self {
             hdr: libc::cmsghdr {
-                // on Linux this is a usize, on macOS this is a u32
-                #[allow(clippy::unnecessary_cast)]
-                cmsg_len: (mem::offset_of!(Self, data) + N) as _,
+                // on Linux this is a usize
+                cmsg_len: mem::offset_of!(Self, data) + N,
                 cmsg_level: level,
                 cmsg_type: typ,
             },
@@ -42,24 +41,29 @@ impl<const N: usize> Cmsg<N> {
 /// A wrapper around [`libc::sendmsg`].
 pub(crate) fn sendmsg<const N: usize>(
     fd: RawFd,
-    data: &[io::IoSlice<'_>],
+    data: &mut [io::IoSlice<'_>],
     cmsg: Option<&Cmsg<N>>,
     flags: i32,
 ) -> io::Result<usize> {
-    let mut msg: libc::msghdr = unsafe { std::mem::zeroed() };
+    #[allow(unsafe_code)]
+    // SAFETY: zeroed is fine for msghdr as we will set all the fields we use.
+    let mut msg: libc::msghdr = unsafe { mem::zeroed() };
 
     if let Some(cmsg) = cmsg {
-        msg.msg_control = cmsg as *const _ as *mut c_void;
-        msg.msg_controllen = std::mem::size_of_val(cmsg);
+        msg.msg_control = ptr::from_ref(cmsg) as *mut c_void;
+        msg.msg_controllen = size_of_val(cmsg);
     }
 
-    msg.msg_iov = data.as_ptr() as *const _ as *mut libc::iovec;
+    msg.msg_iov = ptr::from_mut(data).cast();
     msg.msg_iovlen = data.len();
 
+    #[allow(unsafe_code)]
+    // SAFETY: syscall
     let ret = unsafe { libc::sendmsg(fd, &msg, flags) };
     match ret {
-        -1 => Err(io::Error::last_os_error()),
-        len => Ok(len as usize),
+        ..0 => Err(io::Error::last_os_error()),
+        #[allow(clippy::cast_sign_loss)]
+        len @ 0.. => Ok(len as usize),
     }
 }
 
@@ -79,10 +83,13 @@ pub(crate) fn recvmsg_whole<const N: usize>(
     }
 
     loop {
-        let mut msg: libc::msghdr = unsafe { std::mem::zeroed() };
+        #[allow(unsafe_code)]
+        // SAFETY: zeroed is fine for msghdr as we will set all the fields we use.
+        let mut msg: libc::msghdr = unsafe { mem::zeroed() };
+
         if let Some(cmsg) = cmsg.as_deref_mut() {
-            msg.msg_control = cmsg as *mut _ as *mut c_void;
-            msg.msg_controllen = std::mem::size_of_val(cmsg);
+            msg.msg_control = ptr::from_mut(cmsg).cast();
+            msg.msg_controllen = size_of_val(cmsg);
         }
 
         if data.spare_capacity_mut().is_empty() {
@@ -91,23 +98,28 @@ pub(crate) fn recvmsg_whole<const N: usize>(
 
         let spare = data.spare_capacity_mut();
         let mut iov = libc::iovec {
-            iov_base: spare.as_mut_ptr() as *mut c_void,
+            iov_base: spare.as_mut_ptr().cast(),
             iov_len: spare.len(),
         };
 
         msg.msg_iov = &mut iov;
         msg.msg_iovlen = 1;
 
+        #[allow(unsafe_code)]
         // SAFETY: We have made sure to initialize msg with valid pointers (or NULL).
         let ret = unsafe { libc::recvmsg(fd, &mut msg, flags) };
         let count = match ret {
-            -1 => return Err(io::Error::last_os_error()),
-            len => len as usize,
+            ..0 => return Err(io::Error::last_os_error()),
+            #[allow(clippy::cast_sign_loss)]
+            len @ 0.. => len as usize,
         };
 
+        #[allow(unsafe_code)]
         // SAFETY: recvmsg has just written count to the bytes in the spare capacity of
         //         the vector.
-        unsafe { data.set_len(data.len() + count) };
+        unsafe {
+            data.set_len(data.len() + count);
+        };
 
         if msg.msg_flags & libc::MSG_EOR != 0 {
             break Ok(msg.msg_flags);

ktls/src/lib.rs

@@ -1,4 +1,22 @@
 #![doc = include_str!("../README.md")]
+#![warn(
+    unsafe_code,
+    unused_must_use,
+    clippy::alloc_instead_of_core,
+    clippy::exhaustive_enums,
+    clippy::exhaustive_structs,
+    clippy::manual_let_else,
+    clippy::use_self,
+    clippy::upper_case_acronyms,
+    elided_lifetimes_in_paths,
+    missing_docs,
+    trivial_casts,
+    trivial_numeric_casts,
+    unreachable_pub,
+    unused_import_braces,
+    unused_extern_crates,
+    unused_qualifications
+)]
 
 #[cfg(not(target_os = "linux"))]
 compile_error!("This crate only supports Linux");

ktls/src/protocol.rs

@@ -21,7 +21,7 @@ macro_rules! c_enum {
         impl $name {
             $(
                 $( #[$vattr] )*
-                pub const $variant: Self = Self($value);
+                $vis const $variant: Self = Self($value);
             )*
         }
 
@@ -65,10 +65,10 @@ macro_rules! c_enum {
     }
 }
 
-/// KeyUpdate, not requested
+/// `KeyUpdate`, not requested
 pub(crate) const KEY_UPDATE_NOT_REQUESTED: u8 = 0;
 
-/// KeyUpdate, requested
+/// `KeyUpdate`, requested
 pub(crate) const KEY_UPDATE_REQUESTED: u8 = 1;
 
 c_enum! {

ktls/src/setup.rs

@@ -1,7 +1,27 @@
-//! This module provides low-level APIs to setup a kTLS connection.
+//! Transport Layer Security (TLS) is a Upper Layer Protocol (ULP) that runs
+//! over TCP. TLS provides end-to-end data integrity and confidentiality.
+//!
+//! Once the TCP connection is established, sets the TLS ULP, which allows us to
+//! set/get TLS socket options.
+//!
+//! This module provides the [`setup_ulp`] function, which sets the ULP (Upper
+//! Layer Protocol) to TLS for a TCP socket. The user can also determine whether
+//! the kernel supports kTLS with [`setup_ulp`].
+//!
+//! After the TLS handshake is completed, we have all the parameters required to
+//! move the data-path to the kernel. There is a separate socket option for
+//! moving the transmit and the receive into the kernel.
+//!
+//! This module provides the low-level [`setup_tls_params`] function (when
+//! feature `raw-api` is enabled), which sets the Kernel TLS parameters on the
+//! TCP socket, allowing the kernel to handle encryption and decryption of the
+//! TLS data.
 
-pub(crate) mod tls;
+mod tls;
 mod ulp;
 
-pub use tls::setup_tls_params;
+#[cfg(not(feature = "raw-api"))]
+pub(crate) use tls::{setup_tls_params, setup_tls_params_rx, setup_tls_params_tx};
+#[cfg(feature = "raw-api")]
+pub use tls::{setup_tls_params, setup_tls_params_rx, setup_tls_params_tx};
 pub use ulp::{setup_ulp, SetupError};