oxitls-core — Core traits and types for OxiTLS

oxitls-core defines the foundational API surface shared across the OxiTLS ecosystem: error types, TLS version and cipher-suite enumerations, post-handshake connection metadata, key-logging policy, RFC 8446 alert codes, and the object-safe connector/acceptor traits that every OxiTLS adapter implements. It contains no handshake logic — concrete TLS providers live in the adapter crates (oxitls-adapter-rustls-rustcrypto, oxitls-adapter-aws-lc, oxitls-adapter-pkcs11) and are surfaced through the oxitls façade.

This crate is Pure Rust (#![forbid(unsafe_code)]). It builds on rustls for the underlying TLS state types; combined with the RustCrypto-backed provider (oxitls-adapter-rustls-rustcrypto) the whole stack contains no C/C++/Fortran. The OS-entropy adapter [OsRng] is sourced from getrandom and intentionally implements the rand_core 0.6 traits required by rsa, ed25519-dalek, and x25519-dalek.

Installation

[dependencies]
oxitls-core = "0.2.0"

To opt into the generic (transport-preserving) connector/acceptor traits:

[dependencies]
oxitls-core = { version = "0.2.0", features = ["generic-transport"] }

Quick Start

use oxitls_core::{CipherSuite, ConnectionInfoBuilder, TlsVersion};

// Build post-handshake connection metadata (adapters populate this for you).
let info = ConnectionInfoBuilder::new()
    .version(TlsVersion::Tls13)
    .cipher_suite(CipherSuite::Tls13Aes256GcmSha384)
    .alpn_protocol(b"h2".to_vec())
    .sni("example.com".to_string())
    .build();

assert_eq!(info.version, Some(TlsVersion::Tls13));
assert_eq!(info.alpn_protocol_str(), Some("h2"));

Inspecting cipher suites

use oxitls_core::CipherSuite;

let suite = CipherSuite::Tls13Aes128GcmSha256;
assert_eq!(suite.iana_value(), [0x13, 0x01]);
assert!(suite.is_tls13());
assert_eq!(CipherSuite::from_iana([0x13, 0x01]), Some(suite));

Implementing a connector

use std::future::Future;
use std::pin::Pin;
use oxitls_core::{TlsConnector, TlsError, TlsStream};

struct MyConnector { /* provider config */ }

impl TlsConnector for MyConnector {
    fn connect(
        &self,
        stream: TlsStream,
        server_name: rustls::pki_types::ServerName<'static>,
    ) -> Pin<Box<dyn Future<Output = Result<TlsStream, TlsError>> + Send + '_>> {
        Box::pin(async move {
            // perform the client handshake over `stream` …
            Ok(stream)
        })
    }
}

API Overview

TlsVersion enum

TLS protocol version. Implements Display and FromStr (accepts "TLS 1.3", "tls1.3", "TLSv1.3", "1.3", and the 1.2 equivalents).

TlsVersion::ALL is a &'static [TlsVersion] of all versions in ascending order.

CipherSuite enum

#[non_exhaustive] identifiers covering the TLS 1.3 mandatory suites and the common TLS 1.2 AEAD suites. Implements Display, FromStr, Copy, Eq, Hash.

ConnectionInfo struct

Metadata about a completed TLS connection, populated incrementally by adapter crates after the handshake. Implements Clone, Default.

ConnectionInfoBuilder struct

Fluent builder for [ConnectionInfo] using snake_case setters (version(), cipher_suite(), alpn_protocol(), sni(), peer_certificates()) terminated by build(). Implements Default.

Stream traits

TlsConnector and TlsAcceptor are object-safe (usable via Box<dyn …> / Arc<dyn …>).

Generic transport traits (feature generic-transport)

Transport-preserving variants that retain the concrete underlying stream type S via a generic associated type, avoiding heap allocation of the transport (only the returned future is boxed). These traits are not object-safe — use them through generic bounds.

TlsError enum

#[non_exhaustive] error type. Implements std::error::Error, Display, Clone, PartialEq, and From<io::Error> / From<rustls::Error> (plus From<TlsError> for io::Error).

Predicate helpers: is_handshake(), is_io(), is_cert() (true for BadCert/CertRevoked/CertInvalid), is_config(), is_protocol_violation().

alert module — AlertDescription

#[non_exhaustive] enum of RFC 8446 §6 alert codes (also re-exported at the crate root). Implements Display, Eq, Clone, From<u8>, and to_u8(). Covers the standard alerts (CloseNotify = 0, HandshakeFailure = 40, BadCertificate = 42, UnknownCa = 48, DecryptError = 51, ProtocolVersion = 70, NoApplicationProtocol = 120, …) with an Unknown(u8) catch-all carrying any unrecognised code.

keylog module

Both are re-exported at the crate root.

config module — TlsConfig trait

Generic introspection trait implemented by adapter config structs so higher-level crates can read effective parameters without depending on adapter-specific types.

os_rng module — OsRng

OS-entropy CSPRNG (Clone, Copy, Debug, Default) implementing the rand_core 0.6 RngCore + CryptoRng traits required by rsa 0.9, ed25519-dalek 2.x, and x25519-dalek 2.x. Entropy is drawn from getrandom, decoupling these crates from the workspace rand/rand_core 0.10. Re-exported at the crate root.

stream_info module — connection_info_from

Helper for adapters to build a [ConnectionInfo] from a rustls connection state without orphan-rule problems. Re-exported at the crate root.

let info = oxitls_core::connection_info_from(&tls_conn).unwrap_or_default();

Accepts any C: Deref<Target = rustls::CommonState> and returns None until the handshake has completed. SNI is not populated here (only available on ServerConnection); call with_sni() afterwards if needed.

Feature Flags

Cross-references

• oxitls — the façade that re-exports these types and wires up a provider.
• oxitls-adapter-rustls-rustcrypto — the default Pure-Rust provider implementing TlsConnector / TlsAcceptor.
• oxitls-adapter-aws-lc, oxitls-adapter-pkcs11 — alternative providers.
• oxitls-h2 — HTTP/2 over TLS streams; converts H2Error into [TlsError].
• oxitls-rcgen — certificate generation; errors surface as [TlsError].
• oxitls-webpki-roots — bundled Mozilla root CA store.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)