Skip to content

A lightweight WebAssembly runtime that is fast, secure, and standards-compliant

6.0 KB
Raw Blame
//! # Wasmtime's [wasi-tls] (Transport Layer Security) Implementation
//!
//! This crate provides the Wasmtime host implementation for the [wasi-tls] API.
//! The [wasi-tls] world allows WebAssembly modules to perform SSL/TLS operations,
//! such as establishing secure connections to servers. TLS often relies on other wasi networking systems
//! to provide the stream so it will be common to enable the [wasi:cli] world as well with the networking features enabled.
//!
//! # An example of how to configure [wasi-tls] is the following:
//!
//! ```rust
//! use wasmtime_wasi::{WasiCtx, WasiCtxView, WasiView};
//! use wasmtime::{
//!     component::{Linker, ResourceTable},
//!     Store, Engine, Result,
//! };
//! use wasmtime_wasi_tls::{WasiTlsCtx, WasiTlsCtxBuilder, WasiTlsView, WasiTlsCtxView};
//! use wasmtime_wasi_tls::p2::LinkOptions;
//!
//! struct Ctx {
//!     table: ResourceTable,
//!     wasi_ctx: WasiCtx,
//!     wasi_tls_ctx: WasiTlsCtx,
//! }
//!
//! impl WasiView for Ctx {
//!     fn ctx(&mut self) -> WasiCtxView<'_> {
//!         WasiCtxView { ctx: &mut self.wasi_ctx, table: &mut self.table }
//!     }
//! }
//!
//! impl WasiTlsView for Ctx {
//!     fn tls(&mut self) -> WasiTlsCtxView<'_> {
//!         WasiTlsCtxView { ctx: &mut self.wasi_tls_ctx, table: &mut self.table }
//!     }
//! }
//!
//! #[tokio::main]
//! async fn main() -> Result<()> {
//!     let ctx = Ctx {
//!         table: ResourceTable::new(),
//!         wasi_ctx: WasiCtx::builder()
//!             .inherit_stderr()
//!             .inherit_network()
//!             .allow_ip_name_lookup(true)
//!             .build(),
//!         wasi_tls_ctx: WasiTlsCtxBuilder::new()
//!             // Optionally, configure a specific TLS provider:
//!             // .provider(Box::new(wasmtime_wasi_tls::RustlsProvider::default()))
//!             // .provider(Box::new(wasmtime_wasi_tls::NativeTlsProvider::default()))
//!             // .provider(Box::new(wasmtime_wasi_tls::OpenSslProvider::default()))
//!             .build(),
//!     };
//!
//!     let engine = Engine::default();
//!
//!     // Set up wasi-cli
//!     let mut store = Store::new(&engine, ctx);
//!     let mut linker: Linker<Ctx> = Linker::new(&engine);
//!     wasmtime_wasi::p2::add_to_linker_async(&mut linker)?;
//!
//!     // Add wasi-tls types and turn on the feature in linker
//!     let mut opts = LinkOptions::default();
//!     opts.tls(true);
//!     wasmtime_wasi_tls::p2::add_to_linker(&mut linker, &opts)?;
//!
//!     // ... use `linker` to instantiate within `store` ...
//!     Ok(())
//! }
//!
//! ```
//! [wasi-tls]: https://github.com/WebAssembly/wasi-tls
//! [wasi:cli]: https://docs.rs/wasmtime-wasi/latest

#![deny(missing_docs)]
#![doc(test(attr(deny(warnings))))]
#![doc(test(attr(allow(dead_code, unused_variables, unused_mut))))]

use tokio::io::{AsyncRead, AsyncWrite};
mod error;
mod providers;

/// WASIp2 (`wasi:[email protected]`) host implementation.
#[cfg(feature = "p2")]
pub mod p2;
/// WASIp3 (`wasi:[email protected]`) host implementation.
#[cfg(feature = "p3")]
pub mod p3;

pub use error::Error;
pub use providers::*;

#[cfg(any(feature = "p2", feature = "p3"))]
use wasmtime::component::{HasData, ResourceTable};

/// Builder-style structure used to create a [`WasiTlsCtx`].
#[cfg(any(feature = "p2", feature = "p3"))]
pub struct WasiTlsCtxBuilder {
    provider: Box<dyn TlsProvider>,
}
#[cfg(any(feature = "p2", feature = "p3"))]
impl WasiTlsCtxBuilder {
    /// Creates a builder for a new context with default parameters set.
    pub fn new() -> Self {
        Default::default()
    }

    /// Configure the TLS provider to use for this context.
    ///
    /// By default, this is set to the [`DefaultProvider`] which is picked at
    /// compile time based on feature flags. If this crate is compiled with
    /// multiple TLS providers, this method can be used to specify the provider
    /// at runtime.
    pub fn provider(mut self, provider: Box<dyn TlsProvider>) -> Self {
        self.provider = provider;
        self
    }

    /// Uses the configured context so far to construct the final [`WasiTlsCtx`].
    pub fn build(self) -> WasiTlsCtx {
        WasiTlsCtx {
            provider: self.provider,
        }
    }
}
#[cfg(any(feature = "p2", feature = "p3"))]
impl Default for WasiTlsCtxBuilder {
    fn default() -> Self {
        Self {
            provider: Box::new(DefaultProvider::default()),
        }
    }
}

/// Wasi TLS context needed for internal `wasi-tls` state.
#[cfg(any(feature = "p2", feature = "p3"))]
pub struct WasiTlsCtx {
    pub(crate) provider: Box<dyn TlsProvider>,
}

/// The type for which this crate implements the `wasi:tls` interfaces.
#[cfg(any(feature = "p2", feature = "p3"))]
pub(crate) struct WasiTls;
#[cfg(any(feature = "p2", feature = "p3"))]
impl HasData for WasiTls {
    type Data<'a> = WasiTlsCtxView<'a>;
}

/// View into [`WasiTlsCtx`] implementation and [`ResourceTable`].
#[cfg(any(feature = "p2", feature = "p3"))]
pub struct WasiTlsCtxView<'a> {
    /// Mutable reference to table used to manage resources.
    pub table: &'a mut ResourceTable,

    /// Mutable reference to the WASI TLS context.
    pub ctx: &'a mut WasiTlsCtx,
}

/// A trait which provides internal WASI TLS state.
#[cfg(any(feature = "p2", feature = "p3"))]
pub trait WasiTlsView: Send {
    /// Return a [`WasiTlsCtxView`] from mutable reference to self.
    fn tls(&mut self) -> WasiTlsCtxView<'_>;
}

/// The data stream that carries the encrypted TLS data.
/// Typically this is a TCP stream.
pub trait TlsTransport: AsyncRead + AsyncWrite + Send + Unpin + 'static {}
impl<T: AsyncRead + AsyncWrite + Send + Unpin + ?Sized + 'static> TlsTransport for T {}

/// A TLS connection.
pub trait TlsStream: AsyncRead + AsyncWrite + Send + Unpin + 'static {}

/// A TLS implementation.
pub trait TlsProvider: Send + Sync + 'static {
    /// Set up a client TLS connection using the provided `server_name` and `transport`.
    fn connect(&self, server_name: String, transport: Box<dyn TlsTransport>) -> BoxFutureTlsStream;
}

pub(crate) type BoxFutureTlsStream =
    std::pin::Pin<Box<dyn Future<Output = Result<Box<dyn TlsStream>, Error>> + Send>>;