Crate libtls

Expand description

Rust bindings for LibreSSL’s libtls library.

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 crate provides Rust 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.

§Examples

use libtls::{config::Config, error};

fn tls_server_config() -> error::Result<Config> {
    let mut tls_config = Config::new()?;
    tls_config.set_keypair_file("tests/eccert.crt", "tests/eccert.key")?;
    tls_config.set_protocols(libtls_sys::TLS_PROTOCOL_TLSv1_3);
    Ok(tls_config)
}

fn main() {
    let tls_config = tls_server_config().unwrap();
}

The same configuration can be created using the config::Builder builder pattern:

fn tls_server_config() -> error::Result<Config> {
    let tls_config = Builder::new()
        .keypair_file("tests/eccert.crt", "tests/eccert.key", None)
        .protocols(libtls_sys::TLS_PROTOCOL_TLSv1_3)
        .build()?;
    Ok(tls_config)
}

§Copyright and license

Copyright (c) 2019, 2020 Reyk Floeter <contact@reykfloeter.com>

The documentation is based on the libtls manpages of the LibreSSL project:

Copyright (c) 2015, 2016 Bob Beck <beck@openbsd.org>
Copyright (c) 2016 Brent Cook <bcook@openbsd.org>
Copyright (c) 2017 Claudio Jeker <claudio@openbsd.org>
Copyright (c) 2015 Doug Hogan <doug@openbsd.org>
Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
Copyright (c) 2014, 2015, 2016, 2017, 2018 Joel Sing <jsing@openbsd.org>
Copyright (c) 2015 Reyk Floeter <reyk@openbsd.org>
Copyright (c) 2014, 2015 Ted Unangst <tedu@openbsd.org>

Both are provided under the same OpenBSD-ISC-style license:

Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Modules§

config: TLS configuration for connections.
error: Error handling.
tls: TLS connections, clients and servers.

Macros§

try_tls: Convert return value of Tls I/O functions into io::Error.

Constants§

TLS_API: TLS API version.
TLS_CRL_REASON_AA_COMPROMISE: CRL (RFC 5280 Section 5.3.1).
TLS_CRL_REASON_AFFILIATION_CHANGED: CRL (RFC 5280 Section 5.3.1).
TLS_CRL_REASON_CA_COMPROMISE: CRL (RFC 5280 Section 5.3.1).
TLS_CRL_REASON_CERTIFICATE_HOLD: CRL (RFC 5280 Section 5.3.1).
TLS_CRL_REASON_CESSATION_OF_OPERATION: CRL (RFC 5280 Section 5.3.1).
TLS_CRL_REASON_KEY_COMPROMISE: CRL (RFC 5280 Section 5.3.1).
TLS_CRL_REASON_PRIVILEGE_WITHDRAWN: CRL (RFC 5280 Section 5.3.1).
TLS_CRL_REASON_REMOVE_FROM_CRL: CRL (RFC 5280 Section 5.3.1).
TLS_CRL_REASON_SUPERSEDED: CRL (RFC 5280 Section 5.3.1).
TLS_CRL_REASON_UNSPECIFIED: CRL (RFC 5280 Section 5.3.1).
TLS_MAX_SESSION_ID_LENGTH: TLS session.
TLS_OCSP_CERT_GOOD: OCSP certificate (RFC 6960 Section 2.2).
TLS_OCSP_CERT_REVOKED: OCSP certificate (RFC 6960 Section 2.2).
TLS_OCSP_CERT_UNKNOWN: OCSP certificate (RFC 6960 Section 2.2).
TLS_OCSP_RESPONSE_INTERNALERROR: OCSP response (RFC 6960 Section 2.3).
TLS_OCSP_RESPONSE_MALFORMED: OCSP response (RFC 6960 Section 2.3).
TLS_OCSP_RESPONSE_SIGREQUIRED: OCSP response (RFC 6960 Section 2.3).
TLS_OCSP_RESPONSE_SUCCESSFUL: OCSP response (RFC 6960 Section 2.3).
TLS_OCSP_RESPONSE_TRYLATER: OCSP response (RFC 6960 Section 2.3).
TLS_OCSP_RESPONSE_UNAUTHORIZED: OCSP response (RFC 6960 Section 2.3).
TLS_PROTOCOLS_ALL: TLS major/minor protocol version.
TLS_PROTOCOLS_DEFAULT: TLS major/minor protocol version.
TLS_PROTOCOL_TLSv1: TLS major/minor protocol version.
TLS_PROTOCOL_TLSv1_0: TLS major/minor protocol version.
TLS_PROTOCOL_TLSv1_1: TLS major/minor protocol version.
TLS_PROTOCOL_TLSv1_2: TLS major/minor protocol version.
TLS_PROTOCOL_TLSv1_3: TLSv1.3 is only supported by LibreSSL 3.1.0 or later.
TLS_TICKET_KEY_SIZE: TLS session.
TLS_WANT_POLLIN: TLS async I/O.
TLS_WANT_POLLOUT: TLS async I/O.

Functions§

initDeprecated: Initialize global data structures.