verify_cert: expose builder-like interface for path verification

Author: djc

src/end_entity.rs

@@ -14,24 +14,20 @@
 
 use core::ops::Deref;
 
-use pki_types::{
-    CertificateDer, ServerName, SignatureVerificationAlgorithm, TrustAnchor, UnixTime,
-};
+use pki_types::{CertificateDer, ServerName, SignatureVerificationAlgorithm};
 
-use crate::crl::RevocationOptions;
 use crate::error::Error;
 use crate::subject_name::{verify_dns_names, verify_ip_address_names};
-use crate::verify_cert::{self, ExtendedKeyUsageValidator, VerifiedPath};
 use crate::{cert, sct, signed_data};
 
 /// An end-entity certificate.
 ///
 /// Server certificate processing in a TLS connection consists of several
 /// steps. All of these steps are necessary:
 ///
-/// * [`EndEntityCert::verify_for_usage()`]: Verify that the peer's certificate
-///   is valid for the current usage scenario. For server authentication, use
-///   [`crate::ExtendedKeyUsage::SERVER_AUTH`].
+/// * Build a [`VerifiedPath`][crate::VerifiedPath] using a [PathBuilder][crate::PathBuilder]:
+///   verify that the peer's certificate is valid for the current usage scenario. For server
+///   authentication, use [`crate::ExtendedKeyUsage::SERVER_AUTH`].
 /// * [`EndEntityCert::verify_is_valid_for_subject_name()`]: Verify that the server's
 ///   certificate is valid for the host or IP address that is being connected to.
 /// * [`EndEntityCert::verify_signature()`]: Verify that the signature of server's
@@ -40,9 +36,9 @@ use crate::{cert, sct, signed_data};
 /// Client certificate processing in a TLS connection consists of analogous
 /// steps. All of these steps are necessary:
 ///
-/// * [`EndEntityCert::verify_for_usage()`]: Verify that the peer's certificate
-///   is valid for the current usage scenario. For client authentication, use
-///   [`crate::ExtendedKeyUsage::CLIENT_AUTH`].
+/// * Build a [`VerifiedPath`][crate::VerifiedPath] using a [PathBuilder][crate::PathBuilder]:
+///   verify that the peer's certificate is valid for the current usage scenario. For client
+///   authentication, use [`crate::ExtendedKeyUsage::CLIENT_AUTH`].
 /// * [`EndEntityCert::verify_signature()`]: Verify that the signature of client's
 ///   `CertificateVerify` message is valid using the public key from the
 ///   client's certificate.
@@ -73,54 +69,6 @@ impl<'a> TryFrom<&'a CertificateDer<'a>> for EndEntityCert<'a> {
 }
 
 impl EndEntityCert<'_> {
-    /// Verifies that the end-entity certificate is valid for use against the
-    /// specified Extended Key Usage (EKU).
-    ///
-    /// * `supported_sig_algs` is the list of signature algorithms that are
-    ///   trusted for use in certificate signatures; the end-entity certificate's
-    ///   public key is not validated against this list.
-    /// * `trust_anchors` is the list of root CAs to trust in the built path.
-    /// * `intermediate_certs` is the sequence of intermediate certificates that
-    ///   a peer sent for the purpose of path building.
-    /// * `time` is the time for which the validation is effective (usually the
-    ///   current time).
-    /// * `usage` is the intended usage of the certificate, indicating what kind
-    ///   of usage we're verifying the certificate for. The default [`ExtendedKeyUsageValidator`]
-    ///   implementation is [`ExtendedKeyUsage`](crate::ExtendedKeyUsage).
-    /// * `crls` is the list of certificate revocation lists to check
-    ///   the certificate against.
-    /// * `verify_path` is an optional verification function for path candidates.
-    ///
-    /// If successful, yields a `VerifiedPath` type that can be used to inspect a verified chain
-    /// of certificates that leads from the `end_entity` to one of the `self.trust_anchors`.
-    ///
-    /// `verify_path` will only be called for potentially verified paths, that is, paths that
-    /// have been verified up to the trust anchor. As such, `verify_path()` cannot be used to
-    /// verify a path that doesn't satisfy the constraints listed above; it can only be used to
-    /// reject a path that does satisfy the aforementioned constraints. If `verify_path` returns
-    /// an error, path building will continue in order to try other options.
-    #[expect(clippy::too_many_arguments, clippy::type_complexity)]
-    pub fn verify_for_usage<'p>(
-        &'p self,
-        supported_sig_algs: &[&dyn SignatureVerificationAlgorithm],
-        trust_anchors: &'p [TrustAnchor<'_>],
-        intermediate_certs: &'p [CertificateDer<'p>],
-        time: UnixTime,
-        usage: &dyn ExtendedKeyUsageValidator,
-        revocation: Option<RevocationOptions<'_>>,
-        verify_path: Option<&dyn Fn(&VerifiedPath<'_>) -> Result<(), Error>>,
-    ) -> Result<VerifiedPath<'p>, Error> {
-        verify_cert::PathBuilder {
-            eku: usage,
-            supported_sig_algs,
-            trust_anchors,
-            intermediate_certs,
-            revocation,
-            verify_path,
-        }
-        .build(self, time)
-    }
-
     /// Verifies that the certificate is valid for the given Subject Name.
     pub fn verify_is_valid_for_subject_name(
         &self,

src/lib.rs

@@ -83,7 +83,7 @@ pub use {
     trust_anchor::anchor_from_trusted_cert,
     verify_cert::{
         ExtendedKeyUsage, ExtendedKeyUsageValidator, IntermediateIterator, KeyPurposeId,
-        KeyPurposeIdIter, RequiredEkuNotFoundContext, VerifiedPath,
+        KeyPurposeIdIter, PathBuilder, RequiredEkuNotFoundContext, VerifiedPath,
     },
 };
 

src/verify_cert.rs

@@ -30,10 +30,11 @@ use crate::error::Error;
 use crate::spki_for_anchor;
 use crate::{public_values_eq, subject_name};
 
+/// Build a [`VerifiedPath`] for an end-entity certificate from the given trust anchors.
 // Use `'a` for lifetimes that we don't care about, `'p` for lifetimes that become a part of
 // the `VerifiedPath`.
-pub(crate) struct PathBuilder<'a, 'p> {
-    pub(crate) eku: &'a dyn ExtendedKeyUsageValidator,
+pub struct PathBuilder<'a, 'p> {
+    pub(crate) eku: &'p dyn ExtendedKeyUsageValidator,
     pub(crate) supported_sig_algs: &'a [&'a dyn SignatureVerificationAlgorithm],
     pub(crate) trust_anchors: &'p [TrustAnchor<'p>],
     pub(crate) intermediate_certs: &'p [CertificateDer<'p>],
@@ -43,7 +44,68 @@ pub(crate) struct PathBuilder<'a, 'p> {
 }
 
 impl<'a, 'p: 'a> PathBuilder<'a, 'p> {
-    pub(crate) fn build(
+    /// Build a new [`PathBuilder`] with the given parameters.
+    ///
+    /// * `eku` is the intended usage of the certificate, indicating what kind
+    ///   of usage we're verifying the certificate for. The default [`ExtendedKeyUsageValidator`]
+    ///   implementation is [`ExtendedKeyUsage`](crate::ExtendedKeyUsage).
+    /// * `supported_sig_algs` is the list of signature algorithms that are
+    ///   trusted for use in certificate signatures; the end-entity certificate's
+    ///   public key is not validated against this list.
+    /// * `trust_anchors` is the list of root CAs to trust in the built path.
+    pub fn new(
+        eku: &'p dyn ExtendedKeyUsageValidator,
+        supported_sig_algs: &'a [&'a dyn SignatureVerificationAlgorithm],
+        trust_anchors: &'p [TrustAnchor<'p>],
+    ) -> Self {
+        Self {
+            eku,
+            supported_sig_algs,
+            trust_anchors,
+            intermediate_certs: &[],
+            revocation: None,
+            verify_path: None,
+        }
+    }
+
+    /// Set the sequence of intermediate certificates to use for path building.
+    ///
+    /// These should be sent by the peer. Defaults to empty.
+    pub fn with_intermediate_certs(mut self, intermediate_certs: &'p [CertificateDer<'p>]) -> Self {
+        self.intermediate_certs = intermediate_certs;
+        self
+    }
+
+    /// Set the revocation options to use for path building.
+    ///
+    /// By default, revocation checking is disabled.
+    pub fn with_revocation(mut self, revocation: RevocationOptions<'a>) -> Self {
+        self.revocation = Some(revocation);
+        self
+    }
+
+    /// Set a path verification function to use for path building.
+    ///
+    /// `verify()` will only be called for potentially verified paths, that is, paths that
+    /// have been verified up to the trust anchor. As such, `verify()` cannot be used to
+    /// verify a path that doesn't satisfy the constraints listed above; it can only be used to
+    /// reject a path that does satisfy the aforementioned constraints. If `verify()` returns
+    /// an error, path building will continue in order to try other options.
+    ///
+    /// By default, no additional path verification is done.
+    pub fn with_path_verification(
+        mut self,
+        verify: &'a dyn Fn(&VerifiedPath<'_>) -> Result<(), Error>,
+    ) -> Self {
+        self.verify_path = Some(verify);
+        self
+    }
+
+    /// Build a [`VerifiedPath`] for `end_entity` at the given `time`.
+    ///
+    /// If successful, yields a `VerifiedPath` type that can be used to inspect a verified chain
+    /// of certificates that leads from the `end_entity` to one of the `self.trust_anchors`.
+    pub fn build(
         &self,
         end_entity: &'p EndEntityCert<'p>,
         time: UnixTime,
@@ -173,9 +235,7 @@ impl<'a, 'p: 'a> PathBuilder<'a, 'p> {
     }
 }
 
-/// Path from end-entity certificate to trust anchor that's been verified.
-///
-/// See [`EndEntityCert::verify_for_usage()`] for more details on what verification entails.
+/// Path from end-entity certificate to trust anchor that's been verified by a [`PathBuilder`].
 pub struct VerifiedPath<'p> {
     end_entity: &'p EndEntityCert<'p>,
     intermediates: Intermediates<'p>,
@@ -1361,18 +1421,23 @@ mod tests {
     ) -> Result<VerifiedPath<'a>, ControlFlow<Error, Error>> {
         let time = UnixTime::since_unix_epoch(Duration::from_secs(0x1fed_f00d));
         let mut path = PartialPath::new(ee_cert);
-        let opts = PathBuilder {
-            eku: &ExtendedKeyUsage::SERVER_AUTH,
-            supported_sig_algs: rustls_aws_lc_rs::ALL_VERIFICATION_ALGS,
+
+        let builder = PathBuilder::new(
+            &ExtendedKeyUsage::SERVER_AUTH,
+            rustls_aws_lc_rs::ALL_VERIFICATION_ALGS,
             trust_anchors,
-            intermediate_certs,
-            revocation: None,
-            verify_path,
+        )
+        .with_intermediate_certs(intermediate_certs);
+        let builder = match verify_path {
+            Some(verify) => builder.with_path_verification(verify),
+            None => builder,
         };
 
-        match opts.build_chain_inner(&mut path, time, 0, &mut budget.unwrap_or_default()) {
+        match builder.build_chain_inner(&mut path, time, 0, &mut budget.unwrap_or_default()) {
             Ok(anchor) => Ok(VerifiedPath::new(ee_cert, anchor, path)),
             Err(err) => Err(err),
         }
     }
+
+    //const EKU_SERVER_AUTH: ExtendedKeyUsage = ExtendedKeyUsage::server_auth();
 }