Example for ACME - Lets Encrypt Certificates

[ekanna]

Hi @davidpdrsn
Can you please add an example for Lets Encrypt automatic certificates?
Once you add this, Axum will have almost all the features provided by caddyserver

Thank you.

[davidpdrsn]

I don't know how that works and handling TSL directly is out of scope for axum. It can be handled by hooks provided by hyper. Does the existing TSL examples help you?

[davidpdrsn]

There are also several people in the tokio discord who know more about TSL than me. You can also try asking there.

[ekanna]

Sure, i will try. Thank you.

[nicolaspernoud]

Hello, @ekanna did you manage to use let’s encrypt with axum ? If so, can you provide an example ?

[nicolaspernoud]

Hello,

@davidpdrsn

I have been trying to adapt the tokio/axum tls example here : https://github.com/tokio-rs/axum/blob/main/examples/low-level-rustls/src/main.rs to use with rustls-acme, but I am stuck because the acceptor does not accept a stream, and since tokio does not have the incoming method on the tcp listener, i cannot extract the tcp object as in https://github.com/FlorianUekermann/rustls-acme/blob/8673b2ceeacc02dd8d0a4eea7420e25f08b76102/examples/server_low_level.rs#L62 .

Can you give some insight as to converting the acceptor to be used with this crate ?

[davidpdrsn]

I don't know how to do that unfortunately. Try asking in the hyper channel in the tokio discord server.

[nicolaspernoud]

Thanks, I just did that. If it bear fruits, I will submit a pull request with the example.

[davidpdrsn]

Unless it's very different I'm not sure we need another TLS example 🤔

[nicolaspernoud]

I thing the Let's Encrypt part is pretty specific, and without the help of @FlorianUekermann, I would still be searching.
Anyway, for future reference, there is the working code.
I let you decide if you want to do a proper example of it.

use async_rustls::rustls::Session;
use async_rustls::TlsAcceptor;
use axum::extract::ConnectInfo;
use axum::routing::get;
use axum::Router;
use clap::Parser;
use futures_util::future::poll_fn;
use hyper::server::accept::Accept;
use hyper::server::conn::AddrIncoming;
use hyper::server::conn::Http;
use rustls_acme::acme::ACME_TLS_ALPN_NAME;
use rustls_acme::caches::DirCache;
use rustls_acme::AcmeConfig;
use std::net::SocketAddr;
use std::path::PathBuf;
use std::pin::Pin;
use tokio_stream::StreamExt;
use tokio_util::compat::FuturesAsyncReadCompatExt;
use tokio_util::compat::TokioAsyncReadCompatExt;
use tower::MakeService;

#[derive(Parser, Debug)]
struct Args {
    /// Domains
    #[clap(short, required = true)]
    domains: Vec<String>,

    /// Contact info
    #[clap(short)]
    email: Vec<String>,

    /// Cache directory
    #[clap(short, parse(from_os_str))]
    cache: Option<PathBuf>,

    /// Use Let's Encrypt production environment
    /// (see https://letsencrypt.org/docs/staging-environment/)
    #[clap(long)]
    prod: Option<bool>,

    #[clap(short, long, default_value = "443")]
    port: u16,
}

#[tokio::main]
async fn main() {
    simple_logger::init_with_level(log::Level::Info).unwrap();
    let args = Args::parse();

    let mut state = AcmeConfig::new(args.domains)
        .contact(args.email.iter().map(|e| format!("mailto:{}", e)))
        .cache_option(args.cache.clone().map(DirCache::new))
        .state();
    let acceptor = state.acceptor();

    tokio::spawn(async move {
        loop {
            match state.next().await.unwrap() {
                Ok(ok) => log::info!("event: {:?}", ok),
                Err(err) => log::error!("error: {:?}", err),
            }
        }
    });
    serve(acceptor, args.port).await;
}

async fn serve(acceptor: TlsAcceptor, port: u16) {
    let listener = tokio::net::TcpListener::bind(format!("[::]:{}", port))
        .await
        .unwrap();
    let mut addr_incoming = AddrIncoming::from_listener(listener).unwrap();

    // Create axum application
    let mut app = Router::new()
        .route("/", get(handler))
        .into_make_service_with_connect_info::<SocketAddr>();

    loop {
        let stream = poll_fn(|cx| Pin::new(&mut addr_incoming).poll_accept(cx))
            .await
            .unwrap()
            .unwrap();
        let acceptor = acceptor.clone();

        let app = app.make_service(&stream).await.unwrap();

        tokio::spawn(async move {
            let tls = acceptor.accept(stream.compat()).await.unwrap().compat();
            match tls.get_ref().get_ref().1.get_alpn_protocol() {
                Some(ACME_TLS_ALPN_NAME) => log::info!("received TLS-ALPN-01 validation request"),
                _ => Http::new().serve_connection(tls, app).await.unwrap(),
            }
        });
    }
}

async fn handler(ConnectInfo(addr): ConnectInfo<SocketAddr>) -> String {
    format!("Hello Tls!\nYour address is: {addr}")
}

[casey]

I think a piece of axum middlereware that handles this would be great. I was able to get it working with this example, but I imagine that wanting axum + let's encrypt will be a common use case, so it would be great if this was well supported by an official component. I think the rustls-acme author is more than willing to help making changes that allow axum to be better supported.

[davidpdrsn]

It can be handled by a third party crate. There are so many ways of doing TLS that it's out of scope for inclusion in axum itself.

[nicolaspernoud]

A quick question by the way : any idea to allow a graceful shutdown in this case with the low level serve_connection API ?

[davidpdrsn]

Not sure. Try asking in hyper.

[nicolaspernoud]

Hello,

I managed the graceful shutdown by using tokio channels and a loop.

On a broader subject, can you give a look here : FlorianUekermann/rustls-acme#27 (comment) . The creator of rustls-acme aims to improve the compatibility. I confess I am out of my league, but maybe you can propose something ?!

[nicolaspernoud]

There is now a proper adaptor and an example for axum : https://github.com/FlorianUekermann/rustls-acme/blob/main/examples/low_level_axum.rs !

[alexpyattaev]

May I ask why not use certbot from EFF for ACME and let axum handle the web stuff? Putting ACME into a web framework may be the first step towards turning said framework into a big bloated caddy bear. Certbot has another massive benefit in not using any resources when not actually running certificate updates.

[FlorianUekermann]

May I ask why not use certbot from EFF for ACME and let axum handle the web stuff? Putting ACME into a web framework may be the first step towards turning said framework into a big bloated caddy bear. Certbot has another massive benefit in not using any resources when not actually running certificate updates.

I'm the author of rustls-acme, which can be used with axum to accomplish exactly this (see examples linked above). In the end it comes down to personal preference or your personal opinion on different kinds of complexity. There are a few reasons, why someone may prefer to handle Let's Encrypt stuff inside their web server application:

• Adding a few lines of code to your web server can be easier than maintaining and reproducing a system configuration with certbot.
• Unless you want to run another service or even a separate load-balancer to terminate TLS, you need some code to deal with TLS and certificate updates anyway. Using a library that deals with TLS and certificate acquisition at the same time doesn't add significant complexity in many cases.
• Doing so allows you to use the TLS-ALPN-01 method, which adds no extra requirements on your service like serving the /.well-known/acme-challenge directory.
• Regarding your resource concern: An async task, which practically never runs won't consume more resources than an extra process.
• This approach is aligned with the general shift in preference from configuring system services to combining libraries over the last decade(s). Although you could argue that there is also a trend towards using cloud load-balancer services for TLS termination, if that is your cup of tea.

Also note that the OP asks for adding an example. That doesn't mean axum has to add a new feature. rustls-acme, provides an axum compatible acceptor for this purpose (example).

[alexpyattaev]

You make a really good point. I did not consider that there is a way to bypass the whole .well_known nonsense. Given this, it would indeed be a much cleaner solution than certbot (as long as you can keep your service from overloading the ACME server with requests due to some sort of bug).

[nicolaspernoud]

Well, I use it for months, and it works without bugs for now... TLS-ALPN-01 is very clean, you do not even need to expose anything on port 80 as HTTP. HTTPS only is enough !

[10ne1]

Just want to say thanks for pursuing this, I also started using the rustls-acme crate acceptor with TLS-ALPN-01, works pretty nicely.