itsi-scheduler 0.1.5 → 0.2.2

data/ext/itsi_acme/src/config.rs

@@ -0,0 +1,172 @@
+use crate::acme::{
+    ExternalAccountKey, LETS_ENCRYPT_PRODUCTION_DIRECTORY, LETS_ENCRYPT_STAGING_DIRECTORY,
+};
+use crate::caches::{BoxedErrCache, CompositeCache, NoCache};
+use crate::{AccountCache, Cache, CertCache};
+use crate::{AcmeState, Incoming};
+use futures::Stream;
+use rustls::{ClientConfig, RootCertStore};
+use std::convert::Infallible;
+use std::fmt::Debug;
+use std::sync::Arc;
+use tokio::io::{AsyncRead, AsyncWrite};
+use webpki_roots::TLS_SERVER_ROOTS;
+
+/// Configuration for an ACME resolver.
+///
+/// The type parameters represent the error types for the certificate cache and account cache.
+pub struct AcmeConfig<EC: Debug, EA: Debug = EC> {
+    pub(crate) client_config: Arc<ClientConfig>,
+    pub(crate) directory_url: String,
+    pub(crate) domains: Vec<String>,
+    pub(crate) contact: Vec<String>,
+    pub(crate) cache: Box<dyn Cache<EC = EC, EA = EA>>,
+    pub(crate) eab: Option<ExternalAccountKey>,
+}
+
+impl AcmeConfig<Infallible, Infallible> {
+    /// Creates a new [AcmeConfig] instance.
+    ///
+    /// The new [AcmeConfig] instance will initially have no cache, and its type parameters for
+    /// error types will be `Infallible` since the cache cannot return an error. The methods to set
+    /// a cache will change the error types to match those returned by the supplied cache.
+    ///
+    /// ```rust
+    /// # use tokio_rustls_acme::AcmeConfig;
+    /// use tokio_rustls_acme::caches::DirCache;
+    /// let config = AcmeConfig::new(["example.com"]).cache(DirCache::new("./rustls_acme_cache"));
+    /// ```
+    ///
+    /// Due to limited support for type parameter inference in Rust (see
+    /// [RFC213](https://github.com/rust-lang/rfcs/blob/master/text/0213-defaulted-type-params.md)),
+    /// [AcmeConfig::new] is not (yet) generic over the [AcmeConfig]'s type parameters.
+    /// An uncached instance of [AcmeConfig] with particular type parameters can be created using
+    /// [NoCache].
+    ///
+    /// ```rust
+    /// # use tokio_rustls_acme::AcmeConfig;
+    /// use tokio_rustls_acme::caches::NoCache;
+    /// # type EC = std::io::Error;
+    /// # type EA = EC;
+    /// let config: AcmeConfig<EC, EA> = AcmeConfig::new(["example.com"]).cache(NoCache::new());
+    /// ```
+    ///
+    pub fn new(domains: impl IntoIterator<Item = impl AsRef<str>>) -> Self {
+        let mut root_store = RootCertStore::empty();
+        root_store.extend(
+            TLS_SERVER_ROOTS
+                .iter()
+                .map(|ta| rustls::pki_types::TrustAnchor {
+                    subject: ta.subject.clone(),
+                    subject_public_key_info: ta.subject_public_key_info.clone(),
+                    name_constraints: ta.name_constraints.clone(),
+                }),
+        );
+        let client_config = Arc::new(
+            ClientConfig::builder()
+                .with_root_certificates(root_store)
+                .with_no_client_auth(),
+        );
+        AcmeConfig {
+            client_config,
+            directory_url: LETS_ENCRYPT_STAGING_DIRECTORY.into(),
+            domains: domains.into_iter().map(|s| s.as_ref().into()).collect(),
+            contact: vec![],
+            cache: Box::new(NoCache::new()),
+            eab: None,
+        }
+    }
+}
+
+impl<EC: 'static + Debug, EA: 'static + Debug> AcmeConfig<EC, EA> {
+    /// Set custom `rustls::ClientConfig` for ACME API calls.
+    pub fn client_tls_config(mut self, client_config: Arc<ClientConfig>) -> Self {
+        self.client_config = client_config;
+        self
+    }
+    pub fn directory(mut self, directory_url: impl AsRef<str>) -> Self {
+        self.directory_url = directory_url.as_ref().into();
+        self
+    }
+    pub fn directory_lets_encrypt(mut self, production: bool) -> Self {
+        self.directory_url = match production {
+            true => LETS_ENCRYPT_PRODUCTION_DIRECTORY,
+            false => LETS_ENCRYPT_STAGING_DIRECTORY,
+        }
+        .into();
+        self
+    }
+    pub fn domains(mut self, contact: impl IntoIterator<Item = impl AsRef<str>>) -> Self {
+        self.domains = contact.into_iter().map(|s| s.as_ref().into()).collect();
+        self
+    }
+    pub fn domains_push(mut self, contact: impl AsRef<str>) -> Self {
+        self.domains.push(contact.as_ref().into());
+        self
+    }
+
+    pub fn external_account_binding(mut self, kid: impl AsRef<str>, key: impl AsRef<[u8]>) -> Self {
+        self.eab = Some(ExternalAccountKey::new(kid.as_ref().into(), key.as_ref()));
+        self
+    }
+
+    /// Provide a list of contacts for the account.
+    ///
+    /// Note that email addresses must include a `mailto:` prefix.
+    pub fn contact(mut self, contact: impl IntoIterator<Item = impl AsRef<str>>) -> Self {
+        self.contact = contact.into_iter().map(|s| s.as_ref().into()).collect();
+        self
+    }
+
+    /// Provide a contact for the account.
+    ///
+    /// Note that an email address must include a `mailto:` prefix.
+    pub fn contact_push(mut self, contact: impl AsRef<str>) -> Self {
+        self.contact.push(contact.as_ref().into());
+        self
+    }
+
+    pub fn cache<C: 'static + Cache>(self, cache: C) -> AcmeConfig<C::EC, C::EA> {
+        AcmeConfig {
+            client_config: self.client_config,
+            directory_url: self.directory_url,
+            domains: self.domains,
+            contact: self.contact,
+            cache: Box::new(cache),
+            eab: self.eab,
+        }
+    }
+    pub fn cache_compose<CC: 'static + CertCache, CA: 'static + AccountCache>(
+        self,
+        cert_cache: CC,
+        account_cache: CA,
+    ) -> AcmeConfig<CC::EC, CA::EA> {
+        self.cache(CompositeCache::new(cert_cache, account_cache))
+    }
+    pub fn cache_with_boxed_err<C: 'static + Cache>(self, cache: C) -> AcmeConfig<Box<dyn Debug>> {
+        self.cache(BoxedErrCache::new(cache))
+    }
+    pub fn cache_option<C: 'static + Cache>(self, cache: Option<C>) -> AcmeConfig<C::EC, C::EA> {
+        match cache {
+            Some(cache) => self.cache(cache),
+            None => self.cache(NoCache::<C::EC, C::EA>::new()),
+        }
+    }
+    pub fn state(self) -> AcmeState<EC, EA> {
+        AcmeState::new(self)
+    }
+    /// Turn a stream of TCP connections into a stream of TLS connections.
+    ///
+    /// Specify supported protocol names in `alpn_protocols`, most preferred first. If emtpy (`Vec::new()`), we don't do ALPN.
+    pub fn incoming<
+        TCP: AsyncRead + AsyncWrite + Unpin,
+        ETCP,
+        ITCP: Stream<Item = Result<TCP, ETCP>> + Unpin,
+    >(
+        self,
+        tcp_incoming: ITCP,
+        alpn_protocols: Vec<Vec<u8>>,
+    ) -> Incoming<TCP, ETCP, ITCP, EC, EA> {
+        self.state().incoming(tcp_incoming, alpn_protocols)
+    }
+}

data/ext/itsi_acme/src/https_helper.rs

@@ -0,0 +1,69 @@
+use rustls::{pki_types::InvalidDnsNameError, ClientConfig};
+use thiserror::Error;
+
+pub use reqwest::Response;
+
+#[derive(Copy, Clone)]
+pub enum Method {
+    Post,
+    Get,
+    Head,
+}
+
+impl From<Method> for reqwest::Method {
+    fn from(m: Method) -> Self {
+        match m {
+            Method::Post => reqwest::Method::POST,
+            Method::Get => reqwest::Method::GET,
+            Method::Head => reqwest::Method::HEAD,
+        }
+    }
+}
+
+pub(crate) async fn https(
+    client_config: &ClientConfig,
+    url: impl AsRef<str>,
+    method: Method,
+    body: Option<String>,
+) -> Result<Response, HttpsRequestError> {
+    let method: reqwest::Method = method.into();
+    let client = reqwest::ClientBuilder::new()
+        .use_preconfigured_tls(client_config.clone())
+        .build()?;
+    let mut request = client.request(method, url.as_ref());
+    if let Some(body) = body {
+        request = request
+            .body(body)
+            .header("Content-Type", "application/jose+json");
+    }
+
+    let response = request.send().await?;
+    let status = response.status();
+    if !status.is_success() {
+        return Err(HttpsRequestError::Non2xxStatus {
+            status_code: status.into(),
+            body: response.text().await?,
+        });
+    }
+    Ok(response)
+}
+
+impl From<reqwest::Error> for HttpsRequestError {
+    fn from(e: reqwest::Error) -> Self {
+        Self::Http(e.into())
+    }
+}
+
+#[derive(Error, Debug)]
+pub enum HttpsRequestError {
+    #[error("io error: {0:?}")]
+    Io(#[from] std::io::Error),
+    #[error("invalid dns name: {0:?}")]
+    InvalidDnsName(#[from] InvalidDnsNameError),
+    #[error("http error: {0:?}")]
+    Http(Box<dyn std::error::Error + Send + Sync + 'static>),
+    #[error("non 2xx http status: {status_code} {body:?}")]
+    Non2xxStatus { status_code: u16, body: String },
+    #[error("could not determine host from url")]
+    UndefinedHost,
+}

data/ext/itsi_acme/src/incoming.rs

@@ -0,0 +1,142 @@
+use crate::acceptor::{AcmeAccept, AcmeAcceptor};
+use crate::AcmeState;
+use futures::stream::{FusedStream, FuturesUnordered};
+use futures::Stream;
+use rustls::ServerConfig;
+use std::fmt::Debug;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::task::{Context, Poll};
+use tokio::io::{AsyncRead, AsyncWrite};
+use tokio_rustls::{server::TlsStream, Accept};
+
+pub struct Incoming<
+    TCP: AsyncRead + AsyncWrite + Unpin,
+    ETCP,
+    ITCP: Stream<Item = Result<TCP, ETCP>> + Unpin,
+    EC: Debug + 'static,
+    EA: Debug + 'static,
+> {
+    state: AcmeState<EC, EA>,
+    acceptor: AcmeAcceptor,
+    rustls_config: Arc<ServerConfig>,
+    tcp_incoming: Option<ITCP>,
+    acme_accepting: FuturesUnordered<AcmeAccept<TCP>>,
+    tls_accepting: FuturesUnordered<Accept<TCP>>,
+}
+
+impl<
+        TCP: AsyncRead + AsyncWrite + Unpin,
+        ETCP,
+        ITCP: Stream<Item = Result<TCP, ETCP>> + Unpin,
+        EC: Debug + 'static,
+        EA: Debug + 'static,
+    > Unpin for Incoming<TCP, ETCP, ITCP, EC, EA>
+{
+}
+
+impl<
+        TCP: AsyncRead + AsyncWrite + Unpin,
+        ETCP,
+        ITCP: Stream<Item = Result<TCP, ETCP>> + Unpin,
+        EC: Debug + 'static,
+        EA: Debug + 'static,
+    > Incoming<TCP, ETCP, ITCP, EC, EA>
+{
+    pub fn new(
+        tcp_incoming: ITCP,
+        state: AcmeState<EC, EA>,
+        acceptor: AcmeAcceptor,
+        alpn_protocols: Vec<Vec<u8>>,
+    ) -> Self {
+        let mut config = ServerConfig::builder()
+            .with_no_client_auth()
+            .with_cert_resolver(state.resolver());
+        config.alpn_protocols = alpn_protocols;
+        Self {
+            state,
+            acceptor,
+            rustls_config: Arc::new(config),
+            tcp_incoming: Some(tcp_incoming),
+            acme_accepting: FuturesUnordered::new(),
+            tls_accepting: FuturesUnordered::new(),
+        }
+    }
+}
+
+impl<
+        TCP: AsyncRead + AsyncWrite + Unpin,
+        ETCP,
+        ITCP: Stream<Item = Result<TCP, ETCP>> + Unpin,
+        EC: Debug + 'static,
+        EA: Debug + 'static,
+    > Stream for Incoming<TCP, ETCP, ITCP, EC, EA>
+{
+    type Item = Result<TlsStream<TCP>, ETCP>;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        loop {
+            match Pin::new(&mut self.state).poll_next(cx) {
+                Poll::Ready(Some(event)) => {
+                    match event {
+                        Ok(ok) => log::info!("event: {:?}", ok),
+                        Err(err) => log::error!("event: {:?}", err),
+                    }
+                    continue;
+                }
+                Poll::Ready(None) => unreachable!(),
+                Poll::Pending => {}
+            }
+            match Pin::new(&mut self.acme_accepting).poll_next(cx) {
+                Poll::Ready(Some(Ok(Some(tls)))) => self
+                    .tls_accepting
+                    .push(tls.into_stream(self.rustls_config.clone())),
+                Poll::Ready(Some(Ok(None))) => {
+                    log::info!("received TLS-ALPN-01 validation request");
+                    continue;
+                }
+                Poll::Ready(Some(Err(err))) => {
+                    log::error!("tls accept failed, {:?}", err);
+                    continue;
+                }
+                Poll::Ready(None) | Poll::Pending => {}
+            }
+            match Pin::new(&mut self.tls_accepting).poll_next(cx) {
+                Poll::Ready(Some(Ok(tls))) => return Poll::Ready(Some(Ok(tls))),
+                Poll::Ready(Some(Err(err))) => {
+                    log::error!("tls accept failed, {:?}", err);
+                    continue;
+                }
+                Poll::Ready(None) | Poll::Pending => {}
+            }
+            let tcp_incoming = match &mut self.tcp_incoming {
+                Some(tcp_incoming) => tcp_incoming,
+                None => match self.is_terminated() {
+                    true => return Poll::Ready(None),
+                    false => return Poll::Pending,
+                },
+            };
+            match Pin::new(tcp_incoming).poll_next(cx) {
+                Poll::Ready(Some(Ok(tcp))) => self.acme_accepting.push(self.acceptor.accept(tcp)),
+                Poll::Ready(Some(Err(err))) => return Poll::Ready(Some(Err(err))),
+                Poll::Ready(None) => drop(self.tcp_incoming.as_mut()),
+                Poll::Pending => return Poll::Pending,
+            }
+        }
+    }
+}
+
+impl<
+        TCP: AsyncRead + AsyncWrite + Unpin,
+        ETCP,
+        ITCP: Stream<Item = Result<TCP, ETCP>> + Unpin,
+        EC: Debug + 'static,
+        EA: Debug + 'static,
+    > FusedStream for Incoming<TCP, ETCP, ITCP, EC, EA>
+{
+    fn is_terminated(&self) -> bool {
+        self.tcp_incoming.is_none()
+            && self.acme_accepting.is_terminated()
+            && self.tls_accepting.is_terminated()
+    }
+}

data/ext/itsi_acme/src/jose.rs

@@ -0,0 +1,161 @@
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use base64::Engine;
+use ring::digest::{digest, Digest, SHA256};
+use ring::rand::SystemRandom;
+use ring::signature::{EcdsaKeyPair, KeyPair};
+use serde::Serialize;
+use thiserror::Error;
+
+pub(crate) fn sign(
+    key: &EcdsaKeyPair,
+    kid: Option<&str>,
+    nonce: String,
+    url: &str,
+    payload: &str,
+) -> Result<String, JoseError> {
+    let jwk = match kid {
+        None => Some(Jwk::new(key)),
+        Some(_) => None,
+    };
+    let protected = Protected::base64(jwk, kid, Some(nonce.as_ref()), url)?;
+    let payload = URL_SAFE_NO_PAD.encode(payload);
+    let combined = format!("{}.{}", &protected, &payload);
+    let signature = key.sign(&SystemRandom::new(), combined.as_bytes())?;
+    let signature = URL_SAFE_NO_PAD.encode(signature.as_ref());
+    let body = Body {
+        protected,
+        payload,
+        signature,
+    };
+    Ok(serde_json::to_string(&body)?)
+}
+
+pub(crate) fn sign_eab(
+    key: &EcdsaKeyPair,
+    eab_key: &ring::hmac::Key,
+    kid: &str,
+    url: &str,
+) -> Result<Body, JoseError> {
+    let protected = Protected::hmac_base64(kid, url)?;
+    let payload = URL_SAFE_NO_PAD.encode(serde_json::to_vec(&Jwk::new(key))?);
+    let combined = format!("{}.{}", &protected, &payload);
+    let signature = ring::hmac::sign(eab_key, combined.as_bytes());
+    let signature = URL_SAFE_NO_PAD.encode(signature.as_ref());
+    let body = Body {
+        protected,
+        payload,
+        signature,
+    };
+    Ok(body)
+}
+
+pub(crate) fn key_authorization_sha256(
+    key: &EcdsaKeyPair,
+    token: &str,
+) -> Result<Digest, JoseError> {
+    let jwk = Jwk::new(key);
+    let key_authorization = format!("{}.{}", token, jwk.thumb_sha256_base64()?);
+    Ok(digest(&SHA256, key_authorization.as_bytes()))
+}
+
+#[derive(Serialize)]
+pub(crate) struct Body {
+    protected: String,
+    payload: String,
+    signature: String,
+}
+
+#[derive(Serialize)]
+struct Protected<'a> {
+    alg: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    jwk: Option<Jwk>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    kid: Option<&'a str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    nonce: Option<&'a str>,
+    url: &'a str,
+}
+
+impl<'a> Protected<'a> {
+    fn base64(
+        jwk: Option<Jwk>,
+        kid: Option<&'a str>,
+        nonce: Option<&'a str>,
+        url: &'a str,
+    ) -> Result<String, JoseError> {
+        let protected = Self {
+            alg: "ES256",
+            jwk,
+            kid,
+            nonce,
+            url,
+        };
+        let protected = serde_json::to_vec(&protected)?;
+        Ok(URL_SAFE_NO_PAD.encode(protected))
+    }
+
+    fn hmac_base64(kid: &'a str, url: &'a str) -> Result<String, JoseError> {
+        let protected = Self {
+            alg: "HS256",
+            jwk: None,
+            kid: Some(kid),
+            nonce: None,
+            url,
+        };
+        let protected = serde_json::to_vec(&protected)?;
+        Ok(URL_SAFE_NO_PAD.encode(protected))
+    }
+}
+
+#[derive(Serialize)]
+struct Jwk {
+    alg: &'static str,
+    crv: &'static str,
+    kty: &'static str,
+    #[serde(rename = "use")]
+    u: &'static str,
+    x: String,
+    y: String,
+}
+
+impl Jwk {
+    pub(crate) fn new(key: &EcdsaKeyPair) -> Self {
+        let (x, y) = key.public_key().as_ref()[1..].split_at(32);
+        Self {
+            alg: "ES256",
+            crv: "P-256",
+            kty: "EC",
+            u: "sig",
+            x: URL_SAFE_NO_PAD.encode(x),
+            y: URL_SAFE_NO_PAD.encode(y),
+        }
+    }
+    pub(crate) fn thumb_sha256_base64(&self) -> Result<String, JoseError> {
+        let jwk_thumb = JwkThumb {
+            crv: self.crv,
+            kty: self.kty,
+            x: &self.x,
+            y: &self.y,
+        };
+        let json = serde_json::to_vec(&jwk_thumb)?;
+        let hash = digest(&SHA256, &json);
+        Ok(URL_SAFE_NO_PAD.encode(hash))
+    }
+}
+
+#[derive(Serialize)]
+struct JwkThumb<'a> {
+    crv: &'a str,
+    kty: &'a str,
+    x: &'a str,
+    y: &'a str,
+}
+
+#[derive(Error, Debug)]
+pub enum JoseError {
+    #[error("json serialization failed: {0}")]
+    Json(#[from] serde_json::Error),
+    #[error("crypto error: {0}")]
+    Crypto(#[from] ring::error::Unspecified),
+}

data/ext/itsi_acme/src/lib.rs

@@ -0,0 +1,142 @@
+//! An easy-to-use, async compatible [ACME] client library using [rustls] with [ring].
+//! The validation mechanism used is tls-alpn-01, which allows serving acme challenge responses and
+//! regular TLS traffic on the same port.
+//!
+//! Is designed to use the tokio runtime, if you need support for other runtimes take a look
+//! at the original implementation [rustls-acme](https://github.com/FlorianUekermann/rustls-acme).
+//!
+//! No persistent tasks are spawned under the hood and the certificate acquisition/renewal process
+//! is folded into the streams and futures being polled by the library user.
+//!
+//! The goal is to provide a [Let's Encrypt](https://letsencrypt.org/) compatible TLS serving and
+//! certificate management using a simple and flexible stream based API.
+//!
+//! This crate uses [ring] as [rustls]'s backend, instead of [aws-lc-rs]. This generally makes it
+//! much easier to compile. If you'd like to use [aws-lc-rs] as [rustls]'s backend, we're open to
+//! contributions with the necessary `Cargo.toml` changes and feature-flags to enable you to do so.
+//!
+//! To use tokio-rustls-acme add the following lines to your `Cargo.toml`:
+//!
+//! ```toml
+//! [dependencies]
+//! tokio-rustls-acme = "*"
+//! ```
+//!
+//! ## High-level API
+//!
+//! The high-level API consists of a single stream [Incoming] of incoming TLS connection.
+//! Polling the next future of the stream takes care of acquisition and renewal of certificates, as
+//! well as accepting TLS connections, which are handed over to the caller on success.
+//!
+//! ```rust,no_run
+//! use tokio::io::AsyncWriteExt;
+//! use futures::StreamExt;
+//! use tokio_rustls_acme::{AcmeConfig, caches::DirCache};
+//! use tokio_stream::wrappers::TcpListenerStream;
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     simple_logger::init_with_level(log::Level::Info).unwrap();
+//!
+//!     let tcp_listener = tokio::net::TcpListener::bind("[::]:443").await.unwrap();
+//!     let tcp_incoming = TcpListenerStream::new(tcp_listener);
+//!
+//!     let mut tls_incoming = AcmeConfig::new(["example.com"])
+//!         .contact_push("mailto:admin@example.com")
+//!         .cache(DirCache::new("./rustls_acme_cache"))
+//!         .incoming(tcp_incoming, Vec::new());
+//!
+//!     while let Some(tls) = tls_incoming.next().await {
+//!         let mut tls = tls.unwrap();
+//!         tokio::spawn(async move {
+//!             tls.write_all(HELLO).await.unwrap();
+//!             tls.shutdown().await.unwrap();
+//!         });
+//!     }
+//! }
+//!
+//! const HELLO: &'static [u8] = br#"HTTP/1.1 200 OK
+//! Content-Length: 11
+//! Content-Type: text/plain; charset=utf-8
+//!
+//! Hello Tls!"#;
+//! ```
+//!
+//! `examples/high_level.rs` implements a "Hello Tls!" server similar to the one above, which accepts
+//! domain, port and cache directory parameters.
+//!
+//! Note that all examples use the let's encrypt staging directory by default.
+//! The production directory imposes strict rate limits, which are easily exhausted accidentally
+//! during testing and development.
+//! For testing with the staging directory you may open `https://<your domain>:<port>` in a browser
+//! that allows TLS connections to servers signed by an untrusted CA (in Firefox click "Advanced..."
+//! -> "Accept the Risk and Continue").
+//!
+//! ## Low-level Rustls API
+//!
+//! For users who may want to interact with [rustls] or [tokio_rustls]
+//! directly, the library exposes the underlying certificate management [AcmeState] as well as a
+//! matching resolver [ResolvesServerCertAcme] which implements the [rustls::server::ResolvesServerCert] trait.
+//! See the server_low_level example on how to use the low-level API directly with [tokio_rustls].
+//!
+//! ## Account and certificate caching
+//!
+//! A production server using the let's encrypt production directory must implement both account and
+//! certificate caching to avoid exhausting the let's encrypt API rate limits.
+//! A file based cache using a cache directory is provided by [caches::DirCache].
+//! Caches backed by other persistence layers may be implemented using the [Cache] trait,
+//! or the underlying [CertCache], [AccountCache] traits (contributions welcome).
+//! [caches::CompositeCache] provides a wrapper to combine two implementors of [CertCache] and
+//! [AccountCache] into a single [Cache].
+//!
+//! Note, that the error type parameters of the cache carries over to some other types in this
+//! crate via the [AcmeConfig] they are added to.
+//! If you want to avoid different specializations based on cache type use the
+//! [AcmeConfig::cache_with_boxed_err] method to construct the an [AcmeConfig] object.
+//!
+//!
+//! ## The acme module
+//!
+//! The underlying implementation of an async acme client may be useful to others and is exposed as
+//! a module. It is incomplete (contributions welcome) and not covered by any stability
+//! promises.
+//!
+//! ## Special thanks
+//!
+//! This crate was inspired by the [autocert](https://golang.org/x/crypto/acme/autocert/)
+//! package for [Go](https://golang.org).
+//!
+//! The original implementation of this crate can be found at [FlorianUekermann/rustls-acme](https://github.com/FlorianUekermann/rustls-acme/commits/main), this is just a version focused on supporting only tokio.
+//!
+//! This crate also builds on the excellent work of the authors of
+//! [rustls],
+//! [tokio-rustls](https://github.com/tokio-rs/tls/tree/master/tokio-rustls) and many others.
+//!
+//! [ACME]: https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment
+//! [ring]: https://github.com/briansmith/ring
+//! [rustls]: https://github.com/ctz/rustls
+//! [aws-lc-rs]: https://github.com/aws/aws-lc-rs
+
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
+mod acceptor;
+pub mod acme;
+#[cfg(feature = "axum")]
+pub mod axum;
+mod cache;
+pub mod caches;
+mod config;
+mod https_helper;
+mod incoming;
+mod jose;
+mod resolver;
+mod state;
+
+pub use tokio_rustls;
+
+pub use acceptor::*;
+pub use cache::*;
+pub use config::*;
+pub use incoming::*;
+pub use resolver::*;
+pub use state::*;