Crate tokio_rustls

Asynchronous TLS/SSL streams for Tokio using Rustls.

Why do I need to call poll_flush?

Most TLS implementations will have an internal buffer to improve throughput, and rustls is no exception.

When we write data to TlsStream, we always write rustls buffer first, then take out rustls encrypted data packet, and write it to data channel (like TcpStream). When data channel is pending, some data may remain in rustls buffer.

tokio-rustls To keep it simple and correct, TlsStream will behave like BufWriter. For TlsStream<TcpStream>, this means that data written by poll_write is not guaranteed to be written to TcpStream. You must call poll_flush to ensure that it is written to TcpStream.

You should call poll_flush at the appropriate time, such as when a period of poll_write write is complete and there is no more data to write.

Why don’t we write during poll_read?

We did this in the early days of tokio-rustls, but it caused some bugs. We can solve these bugs through some solutions, but this will cause performance degradation (reverse false wakeup).

And reverse write will also prevent us implement full duplex in the future.

see https://github.com/tokio-rs/tls/issues/40

Why can’t we handle it like native-tls?

When data channel returns to pending, native-tls will falsely report the number of bytes it consumes. This means that if data written by poll_write is not actually written to data channel, it will not return Ready. Thus avoiding the call of poll_flush.

but which does not conform to convention of AsyncWrite trait. This means that if you give inconsistent data in two poll_write, it may cause unexpected behavior.

see https://github.com/tokio-rs/tls/issues/41

Re-exports

• pub use rustls;

Modules

• client
• common 🔒
• server

Macros

• ready 🔒

Structs

• Accept
  Future returned from TlsAcceptor::accept which will resolve once the accept handshake has finished.
• Connect
  Future returned from TlsConnector::connect which will resolve once the connection handshake has finished.
• FallibleAccept
  Like Accept, but returns IO on failure.
• FallibleConnect
  Like Connect, but returns IO on failure.
• LazyConfigAcceptor
• StartHandshake
• TlsAcceptor
  A wrapper around a rustls::ServerConfig, providing an async accept method.
• TlsConnector
  A wrapper around a rustls::ClientConfig, providing an async connect method.

Enums

• TlsStream
  Unified TLS stream type