reyk / rust-libtls

Rust bindings for LibreSSL's libtls library.

Rust bindings for LibreSSL's libtls.

Documentation, Changelog

The LibreSSL project provides a free TLS and crypto stack that was forked from OpenSSL in 2014. The goals are to provide a modernized codebase, improved security, and to apply best practice development processes.

LibreSSL provides C APIs that are compatible to OpenSSL's libssl and libcrypto libraries. It also provides libtls, a new TLS library that is designed to make it easier to write foolproof applications.

This workspace of Rust crates provides language bindings for libtls only, as the other LibreSSL APIs can be used with the existing rust-openssl crate. LibreSSL versions 2.9.0 through 3.1.0 (or later) are supported. TLSv1.3 requires LibreSSL 3.1.0 or later.

The following crates are included:

• libtls-sys: FFI bindings.
• libtls: Rust bindings.
• tokio-libtls: Tokio bindings.

Minimum Rust version

Async I/O with tokio-libtls requires Rust 1.39 or later for async-await. This crate does not provide any backwards compatibility but you can use version 1.0.0 on older Rust versions.

Examples

See the examples directory for various examples to configure, establish, and connect synchronous and asynchronous TLS connections. The following selected example creates a non-blocking and asynchronous TLS connection using Tokio and the tokio-libtls crate:

use std::io;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio_libtls::prelude::*;

async fn async_https_connect(servername: &str) -> io::Result<()> {
    let addr = &(servername.to_owned() + ":443");

    let request = format!(
        "GET / HTTP/1.1\r\n\
         Host: {}\r\n\
         Connection: close\r\n\r\n",
        servername
    );

    let config = Builder::new().build()?;
    let mut tls = connect(addr, &config, None).await?;
    tls.write_all(request.as_bytes()).await?;

    let mut buf = vec![0u8; 1024];
    tls.read_exact(&mut buf).await?;

    let ok = b"HTTP/1.1 200 OK\r\n";
    assert_eq!(&buf[..ok.len()], ok);

    Ok(())
}

#[tokio::main]
async fn main() {
    async_https_connect("www.example.com").await.unwrap();
}

Copyright and license

Licensed under an OpenBSD-ISC-style license, see LICENSE for details.

rust-libtls's Issues

io::Read and io::Write implementations don't handle errors correctly

tls_read, tls_write, and similar functions have three "error" return values. TLS_WANT_POLLIN and TLS_WANT_POLLOUT are correctly converted to ErrorKind::WouldBlock by rust-libtls, but the generic -1 return value is not. The try_tls! macro attempts to cast the return value to usize if isn't WANT_POLLIN or WANT_POLLOUT, which will overflow. The correct behavior would be to call Tls::last_error if the return value is -1.

I'm currently working on a PR to update this library to tokio 0.3 and fix some issues with the async implementation, but once I'm done with that I can write a PR to fix this.

Failing to call `configure` results in a segfault

The current safe API allows the library user to cause a segfault by trying to use Tls::connect without calling Tls::configure first. I'm not sure what the best design to avoid this is, but it caused me a lot of trouble when I didn't realize that Tls::reset also removes the config. Ideally the safe api exposed in the rust bindings would prevent this type of use at compile time.

RUSTSEC-2020-0016: `net2` crate has been deprecated; use `socket2` instead

net2 crate has been deprecated; use socket2 instead

Details
Status	unmaintained
Package	net2
Version	0.2.34
URL	deprecrated/net2-rs@3350e38
Date	2020-05-01

The net2 crate has been deprecated
and users are encouraged to considered socket2 instead.

See advisory page for additional details.