Struct Stream 

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

A thin wrapper around a kTLS offloaded socket.

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

Behaviours

Once receives a close_notify alert from the peer, all subsequent read operations will return EOF (unless the inner buffer contains unread data); once the caller explicitly calls (poll_)shutdown on the stream, a close_notify alert would be sent to the peer and all subsequent write operations will return 0 bytes, indicating that the stream is closed for writing. When the Stream is dropped, it will also perform graceful shutdown automatically.

For TLS 1.2, 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 Stream from the given socket, TLS session and an optional buffer (may be early data received from peer during handshake or a pre-allocated buffer).

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 StreamRefMutRaw which provides low-level access to the inner socket.

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::Errors returned by direct 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.

Errors

See AccessRawStreamError.

pub fn refresh_traffic_keys(&mut self) -> Result<(), Error>

Context::refresh_traffic_keys against the inner socket.

Use with caution, and do check Context::refresh_traffic_keys for details.

Errors

See Context::refresh_traffic_keys.

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 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

Unsupported protocol version or cipher suite, or failure to set up kTLS params on the socket.

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,