https://github.com/pimalaya/io-starttls
I/O-free Rust coroutine to upgrade any plain stream to a secure one
https://github.com/pimalaya/io-starttls
coroutine imap io-free library rust sans-io ssl starttls stream tcp tls
Last synced: 4 months ago
JSON representation
I/O-free Rust coroutine to upgrade any plain stream to a secure one
- Host: GitHub
- URL: https://github.com/pimalaya/io-starttls
- Owner: pimalaya
- License: mit
- Created: 2025-04-20T13:59:21.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-05-17T22:09:13.000Z (about 1 year ago)
- Last Synced: 2025-07-14T16:48:05.330Z (11 months ago)
- Topics: coroutine, imap, io-free, library, rust, sans-io, ssl, starttls, stream, tcp, tls
- Language: Rust
- Homepage: https://docs.rs/io-starttls/latest/io_starttls
- Size: 20.5 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# I/O Opportunistic TLS [](https://docs.rs/io-starttls/latest/io_starttls) [](https://matrix.to/#/#pimalaya:matrix.org)
**I/O-free** Rust coroutine to upgrade any plain stream to a secure one, based on [io-stream](https://github.com/pimalaya/io-stream) and inspired by [@duesee](https://github.com/duesee)'s [blog post](https://duesee.dev/p/avoid-implementing-starttls).
This library allows you to upgrade any plain stream into a secure one using an I/O-agnostic approach, based on 3 concepts:
### Coroutine
A coroutine is an *I/O-free*, *resumable* and *composable* state machine that **emits I/O requests**. A coroutine is considered *terminated* when it does not emit I/O requests anymore.
*See available coroutines at [./src](https://github.com/pimalaya/io-starttls/tree/master/src).*
### Runtime
A runtime contains all the I/O logic, and is responsible for **processing I/O requests** emitted by coroutines.
*See available runtimes at [pimalaya/io-stream](https://github.com/pimalaya/io-stream/tree/master/src/runtimes).*
### Loop
The loop is the glue between coroutines and runtimes. It makes the coroutine progress while allowing runtime to process I/O.
## Examples
### IMAP with blocking std rustls
```rust,ignore
use std::{net::TcpStream, sync::Arc};
use io_starttls::imap::UpgradeTls;
use io_stream::runtimes::std::handle;
use rustls::{ClientConfig, ClientConnection, StreamOwned};
use rustls_platform_verifier::ConfigVerifierExt;
// first connect to IMAP stream using plain TCP
let mut tcp = TcpStream::connect(("posteo.de", 143)).unwrap();
// create a new STARTTLS coroutine
let mut arg = None;
let mut starttls = UpgradeTls::new().with_discard_greeting(true);
while let Err(io) = starttls.resume(arg.take()) {
// handle I/O requests synchronously
arg = Some(handle(&mut tcp, io).unwrap());
}
// now the TCP stream is ready to be upgraded to TLS using rustls
let config = ClientConfig::with_platform_verifier();
let server_name = "posteo.de".to_string().try_into().unwrap();
let conn = ClientConnection::new(Arc::new(config), server_name).unwrap();
let mut tls = StreamOwned::new(conn, tcp);
```
*See complete example at [./examples/std-rustls-imap.rs](https://github.com/pimalaya/io-starttls/blob/master/examples/std-rustls-imap.rs).*
### IMAP with async tokio native-tls
```rust,ignore
use io_starttls::imap::UpgradeTls;
use io_stream::runtimes::tokio::handle;
use tokio::net::TcpStream;
use tokio_native_tls::{native_tls, TlsConnector};
// first connect to IMAP stream using plain TCP
let mut tcp = TcpStream::connect(("posteo.de", 143)).await.unwrap();
// create a new STARTTLS coroutine
let mut arg = None;
let mut starttls = UpgradeTls::new().with_discard_greeting(true);
while let Err(io) = starttls.resume(arg.take()) {
// handle I/O requests synchronously
arg = Some(handle(&mut tcp, io).await.unwrap());
}
// now the TCP stream is ready to be upgraded to TLS using native-tls
let connector = native_tls::TlsConnector::new().unwrap();
let mut tls = TlsConnector::from(connector)
.connect(&host.to_string(), tcp)
.await
.unwrap();
```
*See complete example at [./examples/tokio-native-tls-imap.rs](https://github.com/pimalaya/io-starttls/blob/master/examples/tokio-native-tls-imap.rs).*
## Sponsoring
[](https://nlnet.nl/)
Special thanks to the [NLnet foundation](https://nlnet.nl/) and the [European Commission](https://www.ngi.eu/) that helped the project to receive financial support from various programs:
- [NGI Assure](https://nlnet.nl/project/Himalaya/) in 2022
- [NGI Zero Entrust](https://nlnet.nl/project/Pimalaya/) in 2023
- [NGI Zero Core](https://nlnet.nl/project/Pimalaya-PIM/) in 2024 *(still ongoing)*
If you appreciate the project, feel free to donate using one of the following providers:
[](https://github.com/sponsors/soywod)
[](https://ko-fi.com/soywod)
[](https://www.buymeacoffee.com/soywod)
[](https://liberapay.com/soywod)
[](https://thanks.dev/soywod)
[](https://www.paypal.com/paypalme/soywod)