Path validation: builder/verifier API skeletons

docs/x509/verification.rst

@@ -19,7 +19,7 @@ chain building, etc.
     OS's root of trust, from a well-known source such as a browser CA bundle,
     or from a small set of manually pre-trusted entities.
 
-    :param certs: A list of one or more :class:`~cryptography.x509.Certificate`
+    :param certs: A list of one or more :class:`cryptography.x509.Certificate`
         instances.
 
 .. class:: Subject
@@ -30,6 +30,31 @@ chain building, etc.
     :class:`cryptography.x509.general_name.DNSName`,
     :class:`cryptography.x509.general_name.IPAddress`.
 
+.. class:: ServerVerifier
+
+    .. versionadded:: 42.0.0
+
+    A ServerVerifier verifies server certificates.
+
+    It contains and describes various pieces of configurable path
+    validation logic, such as which subject to expect, how deep prospective
+    validation chains may go, which signature algorithms are allowed, and
+    so forth.
+
+    ServerVerifier instances cannot be constructed directly;
+    :class:`PolicyBuilder` must be used.
+
+    .. attribute:: subject
+
+        :type: :class:`Subject`
+
+        The verifier's subject.
+
+    .. attribute:: validation_time
+
+        :type: :class:`datetime.datetime`
+
+        The verifier's validation time.
 
 .. class:: PolicyBuilder
 
@@ -40,16 +65,16 @@ chain building, etc.
 
     .. method:: time(new_time)
 
-        Sets the policy's verification time.
+        Sets the verifier's verification time.
 
-        :param new_time: The :class:`datetime.datetime` to use in the policy
+        :param new_time: The :class:`datetime.datetime` to use in the verifier
 
         :returns: A new instance of :class:`PolicyBuilder`
 
     .. method:: build_server_verifier(subject)
 
         Builds a verifier for verifying server certificates.
 
-        :param subject: A :class:`Subject` to use in the policy
+        :param subject: A :class:`Subject` to use in the verifier
 
-        :raises NotImplementedError: This API is not implemented yet.
+        :returns: An instance of :class:`ServerVerifier`

src/cryptography/hazmat/bindings/_rust/x509.pyi

@@ -2,6 +2,8 @@
 # 2.0, and the BSD License. See the LICENSE file in the root of this repository
 # for complete details.
 
+import datetime
+
 from cryptography import x509
 from cryptography.hazmat.primitives import hashes
 from cryptography.hazmat.primitives.asymmetric.padding import PSS, PKCS1v15
@@ -35,12 +37,22 @@ def create_x509_crl(
     private_key: PrivateKeyTypes,
     hash_algorithm: hashes.HashAlgorithm | None,
 ) -> x509.CertificateRevocationList: ...
+def create_server_verifier(
+    name: x509.verification.Subject,
+    time: datetime.datetime | None,
+) -> x509.verification.ServerVerifier: ...
 
 class Sct: ...
 class Certificate: ...
 class RevokedCertificate: ...
 class CertificateRevocationList: ...
 class CertificateSigningRequest: ...
 
+class ServerVerifier:
+    @property
+    def subject(self) -> x509.verification.Subject: ...
+    @property
+    def validation_time(self) -> datetime.datetime: ...
+
 class Store:
     def __init__(self, certs: list[x509.Certificate]) -> None: ...

src/cryptography/x509/__init__.py

@@ -171,6 +171,7 @@
 
 __all__ = [
     "certificate_transparency",
+    "verification",
     "load_pem_x509_certificate",
     "load_pem_x509_certificates",
     "load_der_x509_certificate",

src/cryptography/x509/verification.py

@@ -10,12 +10,14 @@
 from cryptography.hazmat.bindings._rust import x509 as rust_x509
 from cryptography.x509.general_name import DNSName, IPAddress
 
-__all__ = ["Store", "Subject", "PolicyBuilder"]
+__all__ = ["Store", "Subject", "ServerVerifier", "PolicyBuilder"]
 
 Store = rust_x509.Store
 
 Subject = typing.Union[DNSName, IPAddress]
 
+ServerVerifier = rust_x509.ServerVerifier
+
 
 class PolicyBuilder:
     def __init__(
@@ -36,9 +38,9 @@ def time(self, new_time: datetime.datetime) -> PolicyBuilder:
             time=new_time,
         )
 
-    def build_server_verifier(self, subject: Subject) -> typing.NoReturn:
+    def build_server_verifier(self, subject: Subject) -> ServerVerifier:
         """
         Builds a verifier for verifying server certificates.
         """
 
-        raise NotImplementedError
+        return rust_x509.create_server_verifier(subject, self._time)

src/rust/cryptography-x509-validation/Cargo.toml

@@ -11,3 +11,6 @@ rust-version = "1.63.0"
 asn1 = { version = "0.15.5", default-features = false }
 cryptography-x509 = { path = "../cryptography-x509" }
 once_cell = "1"
+
+[dev-dependencies]
+pem = "1.1"

src/rust/cryptography-x509-validation/src/policy/mod.rs

@@ -12,6 +12,9 @@ use cryptography_x509::common::{
     PSS_SHA512_MASK_GEN_ALG,
 };
 
+use crate::ops::CryptoOps;
+use crate::types::{DNSName, IPAddress};
+
 // RSASSA‐PKCS1‐v1_5 with SHA‐256
 static RSASSA_PKCS1V15_SHA256: AlgorithmIdentifier<'_> = AlgorithmIdentifier {
     oid: asn1::DefinedByMarker::marker(),
@@ -97,6 +100,39 @@ pub static WEBPKI_PERMITTED_ALGORITHMS: Lazy<HashSet<&AlgorithmIdentifier<'_>>>
     ])
 });
 
+/// Represents a logical certificate "subject," i.e. a principal matching
+/// one of the names listed in a certificate's `subjectAltNames` extension.
+pub enum Subject<'a> {
+    DNS(DNSName<'a>),
+    IP(IPAddress),
+}
+
+/// A `Policy` describes user-configurable aspects of X.509 path validation.
+pub struct Policy<'a, B: CryptoOps> {
+    _ops: B,
+
+    /// A subject (i.e. DNS name or other name format) that any EE certificates
+    /// validated by this policy must match.
+    /// If `None`, the EE certificate must not contain a SAN.
+    pub subject: Option<Subject<'a>>,
+
+    /// The validation time. All certificates validated by this policy must
+    /// be valid at this time.
+    pub validation_time: asn1::DateTime,
+}
+
+impl<'a, B: CryptoOps> Policy<'a, B> {
+    /// Create a new policy with defaults for the certificate profile defined in
+    /// the CA/B Forum's Basic Requirements.
+    pub fn webpki(ops: B, subject: Option<Subject<'a>>, time: asn1::DateTime) -> Self {
+        Self {
+            _ops: ops,
+            subject,
+            validation_time: time,
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use std::ops::Deref;

src/rust/cryptography-x509-validation/src/types.rs

@@ -20,7 +20,7 @@ use std::str::FromStr;
 /// # use cryptography_x509_validation::types::DNSName;
 /// assert_eq!(DNSName::new("foo.com").unwrap(), DNSName::new("FOO.com").unwrap());
 /// ```
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct DNSName<'a>(asn1::IA5String<'a>);
 
 impl<'a> DNSName<'a> {