Add simplified Order::finalize() method

Author: djc

Cargo.toml

@@ -16,6 +16,7 @@ default = ["aws-lc-rs", "hyper-rustls"]
 aws-lc-rs = ["dep:aws-lc-rs", "hyper-rustls?/aws-lc-rs", "rcgen/aws_lc_rs"]
 fips = ["aws-lc-rs", "aws-lc-rs?/fips"]
 hyper-rustls = ["dep:hyper", "dep:hyper-rustls", "dep:hyper-util"]
+rcgen = ["dep:rcgen"]
 ring = ["dep:ring", "hyper-rustls?/ring", "rcgen/ring"]
 
 [dependencies]
@@ -29,6 +30,7 @@ http-body-util = "0.1.2"
 hyper = { version = "1.3.1", features = ["client", "http1", "http2"], optional = true }
 hyper-rustls = { version = "0.27", default-features = false, features = ["http1", "http2", "native-tokio", "tls12", "rustls-native-certs"], optional = true }
 hyper-util = { version = "0.1.5", features = ["client", "client-legacy", "http1", "http2", "tokio"], optional = true }
+rcgen = { version = "0.13", default-features = false, features = ["pem"], optional = true }
 ring = { version = "0.17", features = ["std"], optional = true }
 rustls-pki-types = "1.1.0"
 serde = { version = "1.0.104", features = ["derive"] }
@@ -41,7 +43,6 @@ x509-parser = { version = "0.17", default-features = false, optional = true }
 [dev-dependencies]
 anyhow = "1.0.66"
 clap = { version = "4.0.29", features = ["derive"] }
-rcgen = { version = "0.13", default-features = false, features = ["pem"] }
 rustls = { version = "0.23", default-features = false }
 tempfile = "3"
 tokio = { version = "1.22.0", features = ["macros", "rt", "rt-multi-thread", "time"] }
@@ -50,7 +51,7 @@ tracing-subscriber =  { version = "0.3.16", features = ["env-filter"] }
 
 [[example]]
 name = "provision"
-required-features = ["hyper-rustls"]
+required-features = ["hyper-rustls", "rcgen"]
 
 # Pebble integration test.
 # Ignored by default because it requires pebble & pebble-challtestsrv.

examples/provision.rs

@@ -2,7 +2,6 @@ use std::io;
 use std::time::Duration;
 
 use clap::Parser;
-use rcgen::{CertificateParams, DistinguishedName, KeyPair};
 use tokio::time::sleep;
 use tracing::info;
 
@@ -87,16 +86,9 @@ async fn main() -> anyhow::Result<()> {
         return Err(anyhow::anyhow!("unexpected order status: {status:?}"));
     }
 
-    // If the order is ready, we can provision the certificate.
-    // Use the rcgen library to create a Certificate Signing Request.
-    let mut params = CertificateParams::new(opts.names)?;
-    params.distinguished_name = DistinguishedName::new();
-    let private_key = KeyPair::generate()?;
-    let csr = params.serialize_request(&private_key)?;
-
     // Finalize the order and print certificate chain, private key and account credentials.
 
-    order.finalize(csr.der()).await?;
+    let private_key_pem = order.finalize().await?;
     let cert_chain_pem = loop {
         match order.certificate().await? {
             Some(cert_chain_pem) => break cert_chain_pem,
@@ -105,7 +97,7 @@ async fn main() -> anyhow::Result<()> {
     };
 
     info!("certificate chain:\n\n{cert_chain_pem}");
-    info!("private key:\n\n{}", private_key.serialize_pem());
+    info!("private key:\n\n{private_key_pem}");
     Ok(())
 }
 

src/lib.rs

@@ -24,6 +24,8 @@ use hyper_util::client::legacy::Client as HyperClient;
 use hyper_util::client::legacy::connect::{Connect, HttpConnector};
 #[cfg(feature = "hyper-rustls")]
 use hyper_util::rt::TokioExecutor;
+#[cfg(feature = "rcgen")]
+use rcgen::{CertificateParams, DistinguishedName, KeyPair};
 use serde::Serialize;
 use serde::de::DeserializeOwned;
 use tokio::time::sleep;
@@ -76,12 +78,41 @@ impl Order {
         }
     }
 
+    /// Generate a Certificate Signing Request for the order's identifiers and request finalization
+    ///
+    /// Uses the rcgen crate to generate a Certificate Signing Request (CSR) converting the order's
+    /// identifiers to Subject Alternative Names, then calls [`Order::finalize_csr()`] with it.
+    /// Returns the generated private key, serialized as PEM.
+    ///
+    /// After this succeeds, call [`Order::certificate()`] to retrieve the certificate chain once
+    /// the order is in the appropriate state.
+    #[cfg(feature = "rcgen")]
+    pub async fn finalize(&mut self) -> Result<String, Error> {
+        let mut names = Vec::with_capacity(self.state.authorizations.len());
+        let mut identifiers = self.identifiers();
+        while let Some(result) = identifiers.next().await {
+            names.push(result?.to_string());
+        }
+
+        let mut params = CertificateParams::new(names).map_err(Error::from_rcgen)?;
+        params.distinguished_name = DistinguishedName::new();
+        let private_key = KeyPair::generate().map_err(Error::from_rcgen)?;
+        let csr = params
+            .serialize_request(&private_key)
+            .map_err(Error::from_rcgen)?;
+
+        self.finalize_csr(csr.der()).await?;
+        Ok(private_key.serialize_pem())
+    }
+
     /// Request a certificate from the given Certificate Signing Request (CSR)
     ///
-    /// Creating a CSR is outside of the scope of instant-acme. Make sure you pass in a
-    /// DER representation of the CSR in `csr_der`. Call `certificate()` to retrieve the
-    /// certificate chain once the order is in the appropriate state.
-    pub async fn finalize(&mut self, csr_der: &[u8]) -> Result<(), Error> {
+    /// `csr_der` contains the CSR representation serialized in DER encoding. If you don't need
+    /// custom certificate parameters, [`Order::finalize()`] can generate the CSR for you.
+    ///
+    /// After this succeeds, call [`Order::certificate()`] to retrieve the certificate chain once
+    /// the order is in the appropriate state.
+    pub async fn finalize_csr(&mut self, csr_der: &[u8]) -> Result<(), Error> {
         let rsp = self
             .account
             .post(
@@ -139,6 +170,21 @@ impl Order {
         ))
     }
 
+    /// Retrieve the identifiers for this order
+    ///
+    /// This method will retrieve the identifiers attached to the authorizations for this order
+    /// if they have not been retrieved yet. If you have already consumed the stream generated
+    /// by [`Order::authorizations()`], this will not involve any network activity.
+    pub fn identifiers(&mut self) -> Identifiers<'_> {
+        Identifiers {
+            inner: AuthStream {
+                iter: self.state.authorizations.iter_mut(),
+                nonce: &mut self.nonce,
+                account: &self.account,
+            },
+        }
+    }
+
     /// Poll the order with exponential backoff until in a final state
     ///
     /// Refresh the order state from the server for `tries` times, waiting `delay` before the
@@ -219,6 +265,26 @@ impl Authorizations<'_> {
     }
 }
 
+/// An stream-like interface that yields an [`Order`]'s identifiers
+///
+/// Call [`next()`] to get the next authorization in the order. If the order state
+/// does not yet contain the state of the authorization, it will be fetched from the server.
+///
+/// [`next()`]: Identifiers::next()
+pub struct Identifiers<'a> {
+    inner: AuthStream<'a>,
+}
+
+impl<'a> Identifiers<'a> {
+    /// Yield the next [`Identifier`], fetching the authorization's state if we don't have it yet
+    pub async fn next(&mut self) -> Option<Result<AuthorizedIdentifier<'a>, Error>> {
+        Some(match self.inner.next().await? {
+            Ok((_, state)) => Ok(state.identifier()),
+            Err(err) => Err(err),
+        })
+    }
+}
+
 struct AuthStream<'a> {
     iter: slice::IterMut<'a, Authorization>,
     nonce: &'a mut Option<String>,

src/types.rs

@@ -61,6 +61,13 @@ pub enum Error {
     Str(&'static str),
 }
 
+impl Error {
+    #[cfg(feature = "rcgen")]
+    pub(crate) fn from_rcgen(err: rcgen::Error) -> Self {
+        Self::Other(Box::new(err))
+    }
+}
+
 impl From<&'static str> for Error {
     fn from(s: &'static str) -> Self {
         Error::Str(s)

tests/pebble.rs

@@ -27,7 +27,6 @@ use instant_acme::{
 };
 #[cfg(all(feature = "time", feature = "x509-parser"))]
 use instant_acme::{CertificateIdentifier, RevocationRequest};
-use rcgen::{CertificateParams, DistinguishedName, KeyPair};
 use rustls::RootCertStore;
 use rustls::client::{verify_server_cert_signed_by_trust_anchor, verify_server_name};
 use rustls::crypto::CryptoProvider;
@@ -418,8 +417,7 @@ impl Environment {
         &mut self,
         new_order: &NewOrder<'_>,
     ) -> Result<CertificateDer<'static>, Box<dyn StdError + 'static>> {
-        let identifiers = new_order.identifiers();
-        debug!(?identifiers, "creating order");
+        debug!(identifiers = ?new_order.identifiers(), "creating order");
         let mut order = self.account.new_order(new_order).await?;
         info!(order_url = order.url(), "created order");
 
@@ -451,7 +449,7 @@ impl Environment {
         }
 
         // Issue a certificate for the names, returning the certificate chain.
-        let cert_chain = self.certificate(&mut order, identifiers).await?;
+        let cert_chain = self.certificate(&mut order).await?;
 
         // Split off and parse the EE cert, save the intermediates that follow.
         let (ee_cert_der, intermediates) = cert_chain.split_first().unwrap();
@@ -469,17 +467,16 @@ impl Environment {
         .unwrap();
 
         // Verify the EE cert is valid for each of the identifiers.
-        for ident in identifiers {
-            let domain = match ident {
-                Identifier::Dns(domain) => domain,
-                _ => unreachable!("unsupported identifier {ident:?}"),
-            };
+        let mut identifiers = order.identifiers();
+        while let Some(result) = identifiers.next().await {
+            let ident = result?;
 
             // When verifying a wildcard identifier, use a fixed label under the wildcard.
             // The wildcard identifier isn't a valid ServerName itself.
-            let server_name = match domain.strip_prefix("*.") {
-                Some(rest) => format!("foo.{rest}"),
-                None => domain.to_owned(),
+            let server_name = match (ident.identifier, ident.wildcard) {
+                (Identifier::Dns(domain), true) => format!("foo.{domain}"),
+                (Identifier::Dns(_), false) => ident.to_string(),
+                _ => unreachable!("unsupported identifier {ident:?}"),
             };
 
             verify_server_name(&ee_cert, &ServerName::try_from(server_name)?)?;
@@ -494,27 +491,12 @@ impl Environment {
     async fn certificate(
         &self,
         order: &mut Order,
-        identifiers: &[Identifier],
     ) -> Result<Vec<CertificateDer<'static>>, Box<dyn StdError>> {
-        info!(?identifiers, order_url = order.url(), "issuing certificate");
-
-        // Create a CSR for the identifiers corresponding to the order.
-        let mut params = CertificateParams::new(
-            identifiers
-                .iter()
-                .map(|ident| match ident {
-                    Identifier::Dns(domain) => domain.to_owned(),
-                    _ => unreachable!("unsupported identifier {ident:?}"),
-                })
-                .collect::<Vec<_>>(),
-        )?;
-        params.distinguished_name = DistinguishedName::new();
-        let private_key = KeyPair::generate()?;
-        let csr = params.serialize_request(&private_key)?;
+        info!(order_url = order.url(), "issuing certificate");
 
         // Finalize the order and fetch the issued certificate chain.
         debug!(order_url = order.url(), "finalizing order");
-        order.finalize(csr.der()).await.unwrap();
+        order.finalize().await?;
         debug!(order_url = order.url(), "fetching order certificate chain");
         let cert_chain_pem = loop {
             match order.certificate().await.unwrap() {