salvo_acme/

lib.rs

#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(test, allow(clippy::unwrap_used))]
//! Automatic HTTPS/TLS certificate management for Salvo via the ACME protocol.
//!
//! This crate integrates [certon](https://crates.io/crates/certon), a
//! production-grade ACME client, with Salvo's listener/acceptor system.
//!
//! ## Features
//!
//! - **Multiple issuers**: Let's Encrypt, ZeroSSL, or any ACME-compatible CA.
//! - **Multiple challenge types**: HTTP-01, TLS-ALPN-01, DNS-01.
//! - **On-demand TLS**: obtain certificates at handshake time.
//! - **OCSP stapling**: automatic OCSP response fetching and stapling.
//! - **Multiple key types**: ECDSA P-256/P-384/P-521, RSA, Ed25519.
//! - **Persistent storage**: pluggable storage backend via [`Storage`].
//! - **Background renewal**: automatic certificate renewal and OCSP refresh.
//!
//! ## Certificate key type
//!
//! Salvo ACME defaults to [`KeyType::EcdsaP256`] for newly generated
//! certificate private keys. RSA key types remain available for compatibility,
//! but they are explicit opt-in via [`AcmeConfigBuilder::key_type`] or
//! [`AcmeListenerBuilder::key_type`].
//!
//! ## Quick Start - HTTP-01
//!
//! ```ignore
//! use salvo_acme::AcmeListener;
//! use salvo_core::prelude::*;
//!
//! #[handler]
//! async fn hello() -> &'static str {
//!     "Hello World"
//! }
//!
//! #[tokio::main]
//! async fn main() {
//!     let mut router = Router::new().get(hello);
//!     let listener = TcpListener::new("0.0.0.0:443")
//!         .acme()
//!         .cache_path("acme/letsencrypt")
//!         .add_domain("example.com")
//!         .http01_challenge(&mut router);
//!     let acceptor = listener.join(TcpListener::new("0.0.0.0:80")).bind().await;
//!     Server::new(acceptor).serve(router).await;
//! }
//! ```
//!
//! ## Quick Start - TLS-ALPN-01
//!
//! ```ignore
//! use salvo_acme::AcmeListener;
//! use salvo_core::prelude::*;
//!
//! #[handler]
//! async fn hello() -> &'static str {
//!     "Hello World"
//! }
//!
//! #[tokio::main]
//! async fn main() {
//!     let router = Router::new().get(hello);
//!     let acceptor = TcpListener::new("0.0.0.0:443")
//!         .acme()
//!         .cache_path("acme/letsencrypt")
//!         .add_domain("example.com")
//!         .bind().await;
//!     Server::new(acceptor).serve(router).await;
//! }
//! ```

use salvo_core::cfg_feature;

mod config;
mod listener;

use std::collections::HashMap;
use std::sync::Arc;

pub use config::{AcmeConfig, AcmeConfigBuilder};
pub use listener::{AcmeAcceptor, AcmeListenerBuilder};
use salvo_core::conn::tcp::TcpListener;
use salvo_core::http::StatusError;
use salvo_core::{Depot, FlowCtrl, Handler, Request, Response, async_trait};
use tokio::net::ToSocketAddrs;
use tokio::sync::RwLock;

cfg_feature! {
    #![feature = "quinn"]
    pub use listener::AcmeQuinnListener;
}

// ---------------------------------------------------------------------------
// Re-exports from certon for advanced usage
// ---------------------------------------------------------------------------

/// Re-export the entire `certon` crate for advanced configuration.
pub use certon;
pub use certon::{
    AcmeIssuer, AcmeIssuerBuilder, CertCache, CertIssuer, CertResolver, Certificate,
    Config as CertonConfig, ConfigBuilder as CertonConfigBuilder, DistributedSolver, Dns01Solver,
    DnsProvider, FileStorage, Http01Solver, IssuedCertificate, IssuerPolicy, KeyType,
    LETS_ENCRYPT_PRODUCTION, LETS_ENCRYPT_STAGING, MaintenanceConfig, Manager, OcspConfig,
    OnDemandConfig, PreChecker, Revoker, Solver, Storage, TlsAlpn01Solver, ZEROSSL_PRODUCTION,
    ZeroSslIssuer,
};

// ---------------------------------------------------------------------------
// Constants
// ---------------------------------------------------------------------------

/// Well known ACME challenge path.
pub(crate) const WELL_KNOWN_PATH: &str = "/.well-known/acme-challenge";

/// Challenge type for ACME.
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
#[non_exhaustive]
pub enum ChallengeType {
    /// HTTP-01 challenge.
    ///
    /// Reference: <https://letsencrypt.org/docs/challenge-types/#http-01-challenge>
    Http01,
    /// TLS-ALPN-01 challenge.
    ///
    /// Reference: <https://letsencrypt.org/docs/challenge-types/#tls-alpn-01>
    TlsAlpn01,
    /// DNS-01 challenge.
    ///
    /// Reference: <https://letsencrypt.org/docs/challenge-types/#dns-01-challenge>
    Dns01,
}

// ---------------------------------------------------------------------------
// HTTP-01 challenge handler (Salvo Handler implementation)
// ---------------------------------------------------------------------------

/// Handler for HTTP-01 ACME challenges.
///
/// Reads challenge tokens from a shared map that is populated by the ACME
/// issuance flow. This handler should be registered on the router at
/// `/.well-known/acme-challenge/{token}`.
pub struct Http01Handler {
    pub(crate) keys: Arc<RwLock<HashMap<String, String>>>,
}
impl std::fmt::Debug for Http01Handler {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Http01Handler").finish()
    }
}

#[async_trait]
impl Handler for Http01Handler {
    async fn handle(
        &self,
        req: &mut Request,
        _depot: &mut Depot,
        res: &mut Response,
        _ctrl: &mut FlowCtrl,
    ) {
        if let Some(token) = req.params().get("token") {
            // First check our local map.
            let keys = self.keys.read().await;
            if let Some(value) = keys.get(token) {
                res.render(value);
                return;
            }
            drop(keys);

            // Fall back to certon's global active challenge map.
            if let Some(value) = certon::solvers::get_active_challenge(token) {
                res.render(value);
                return;
            }

            // Log only the length, not the token itself, so log/APM/SIEM
            // pipelines do not become a credential surface for the ACME
            // challenge flow.
            tracing::error!(
                token_len = token.len(),
                "key not found for ACME challenge token"
            );
            res.render(StatusError::not_found().brief("challenge token not found"));
        } else {
            res.render(StatusError::not_found().brief("missing token"));
        }
    }
}

/// Extension trait for Listener to support ACME.
pub trait AcmeListener {
    /// Enable ACME support for the listener.
    fn acme(self) -> AcmeListenerBuilder<Self>
    where
        Self: Sized;
}

impl<T> AcmeListener for TcpListener<T>
where
    T: ToSocketAddrs + Send + 'static,
{
    fn acme(self) -> AcmeListenerBuilder<Self> {
        AcmeListenerBuilder::new(self)
    }
}

#[cfg(test)]
mod tests {
    use salvo_core::http::StatusCode;
    use salvo_core::prelude::*;
    use salvo_core::test::{ResponseExt, TestClient};

    use super::*;

    #[tokio::test]
    async fn http01_handler_serves_known_token() {
        let keys = Arc::new(RwLock::new(HashMap::from([(
            "known".to_owned(),
            "key-authorization".to_owned(),
        )])));
        let handler = Http01Handler { keys };
        let router = Router::with_path(format!("{WELL_KNOWN_PATH}/{{token}}")).goal(handler);

        let mut response = TestClient::get("http://127.0.0.1/.well-known/acme-challenge/known")
            .send(router)
            .await;

        assert_eq!(response.status_code, Some(StatusCode::OK));
        assert_eq!(response.take_string().await.unwrap(), "key-authorization");
    }

    #[tokio::test]
    async fn http01_handler_rejects_unknown_token() {
        let handler = Http01Handler {
            keys: Arc::new(RwLock::new(HashMap::new())),
        };
        let router = Router::with_path(format!("{WELL_KNOWN_PATH}/{{token}}")).goal(handler);

        let response = TestClient::get("http://127.0.0.1/.well-known/acme-challenge/unknown")
            .send(router)
            .await;

        assert_eq!(response.status_code, Some(StatusCode::NOT_FOUND));
    }
}