Struct Stream 

pub struct Stream<S: AsFd, C: TlsSession> { /* private fields */ }

A thin wrapper around a socket with kernel TLS (kTLS) offload configured.

This implements traits Read and Write, AsyncRead and AsyncWrite (when feature async-io-tokio is enabled).

Behaviours

Once a TLS close_notify alert from the peer is received, all subsequent read operations will return EOF.

Once the caller explicitly calls (poll_)shutdown on the stream, all subsequent write operations will return 0 bytes, indicating that the stream is closed for writing.

Once the stream is being dropped, a close_notify alert would be sent to the peer automatically before shutting down the inner socket, according to RFC 8446, section 6.1.

The caller may call (poll_)shutdown on the stream to shutdown explicitly both sides of the stream. Currently, there’s no way provided by this crate to shutdown the TLS stream write side only. For TLS 1.2, this is ideal since once one party sends a close_notify alert, the other party MUST respond with a close_notify alert of its own and close down the connection immediately, according to RFC 5246, section 7.2.1; for TLS 1.3, both parties need not wait to receive a “close_notify” alert before closing their read side of the connection, according to RFC 8446, section 6.1.

Implementations

impl<S: AsFd, C: TlsSession> Stream<S, C>

pub fn new(socket: S, session: C, buffer: Option<Buffer>) -> Self

Creates a new kTLS stream from the given socket, TLS session and an optional buffer (may be early data received from peer during handshaking).

Prerequisites

• The socket must have TLS ULP configured with setup_ulp.
• The TLS handshake must be completed.

pub fn as_mut_raw( &mut self, ) -> Result<StreamRefMutRaw<'_, S, C>, AccessRawStreamError>

Returns a mutable reference to the inner socket if the TLS connection is not closed (unidirectionally or bidirectionally).

This requires a mutable reference to the Stream to ensure a exclusive access to the inner socket.

Notes

• All buffered data MUST be properly consumed (See AccessRawStreamError::HasBufferedData).

  The buffered data typically consists of:

  • Early data received during handshake.
  • Application data received due to improper usage of StreamRefMutRaw::handle_io_error.

• The caller MAY handle any io::Results returned by I/O operations on the inner socket with StreamRefMutRaw::handle_io_error.

• The caller MUST NOT shutdown the inner socket directly, which will lead to undefined behaviours. Instead, the caller MAY call (poll_)shutdown explictly on the Stream to gracefully shutdown the TLS stream (with close_notify be sent) manually, or just drop the stream to do automatic graceful shutdown.

Errors

See AccessRawStreamError.

impl<S, Data> Stream<S, KernelConnection<Data>>

where S: AsFd, KernelConnection<Data>: TlsSession,

pub fn from( socket: S, secrets: ExtractedSecrets, session: KernelConnection<Data>, buffer: Option<Buffer>, ) -> Result<Self, Error>

Constructs a new Stream from a socket, TLS secrets, and TLS session context.

Overview

This creates a Stream from the provided socket, extracted TLS secrets (rustls::ExtractedSecrets), and TLS session context (rustls::kernel::KernelConnection). An optional buffer may be provided for early data received during handshake.

The secrets and context must be extracted from a rustls::client::UnbufferedClientConnection or rustls::client::UnbufferedClientConnection. See rustls::kernel module documentation for more details.

Prerequisites

The socket must have TLS ULP configured with setup_ulp.

Errors

Returns an error if prerequisites aren’t met or kernel TLS setup fails.

impl<C> Stream<TcpStream, C>

where C: TlsSession,

pub fn shutdown(&mut self)

Shuts down both read and write sides of the TLS stream.

impl<C> Stream<UnixStream, C>

where C: TlsSession,

pub fn shutdown(&mut self)

Shuts down both read and write sides of the TLS stream.

Trait Implementations

impl<S, C> AsyncRead for Stream<S, C>

where S: AsFd + AsyncRead, C: TlsSession,

Available on crate feature async-io-tokio only.

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl<S, C> AsyncWrite for Stream<S, C>

where S: AsFd + AsyncWrite, C: TlsSession,

Available on crate feature async-io-tokio only.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl<S: Debug + AsFd, C: Debug + TlsSession> Debug for Stream<S, C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: AsFd, C: TlsSession> Drop for Stream<S, C>

fn drop(&mut self)

Executes the destructor for this type.

impl<S, C> Read for Stream<S, C>

where S: AsFd + Read, C: TlsSession,

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<S, C> Write for Stream<S, C>

where S: AsFd + Write, C: TlsSession,

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl<'__pin, S: AsFd, C: TlsSession> Unpin for Stream<S, C>

where PinnedFieldsOf<__Origin<'__pin, S, C>>: Unpin,