verification: add VerificationError, doc APIs

Signed-off-by: William Woodruff <[email protected]>

docs/x509/verification.rst

@@ -69,6 +69,12 @@ chain building, etc.
 
         The verifier's trust store.
 
+.. class:: VerificationError
+
+    .. versionadded:: 42.0.0
+
+    The error raised when path validation fails.
+
 .. class:: PolicyBuilder
 
     .. versionadded:: 42.0.0
@@ -116,3 +122,17 @@ chain building, etc.
         :param subject: A :class:`Subject` to use in the verifier
 
         :returns: An instance of :class:`ServerVerifier`
+
+    .. method:: verify(leaf, intermediates)
+
+        Performs path validation on ``leaf``, returning a valid path
+        if one exists. The path is returned in leaf-first order:
+        the first member is ``leaf``, followed by the intermediates used
+        (if any), followed by a member of the ``store``.
+
+        :param leaf: The leaf :class:`~cryptography.x509.Certificate` to validate
+        :param intermediates: A :class:`list` of intermediate :class:`~cryptography.x509.Certificate` to attempt to use
+
+        :returns: A list containing a valid chain from ``leaf`` to a member of :class:`ServerVerifier.store`.
+
+        :raises VerificationError: If a valid chain cannot be constructed

src/cryptography/x509/verification.py

@@ -19,6 +19,10 @@
 ServerVerifier = rust_x509.ServerVerifier
 
 
+class VerificationError(Exception):
+    pass
+
+
 class PolicyBuilder:
     def __init__(
         self,

src/rust/src/exceptions.rs

@@ -32,6 +32,7 @@ pyo3::import_exception!(cryptography.x509, AttributeNotFound);
 pyo3::import_exception!(cryptography.x509, DuplicateExtension);
 pyo3::import_exception!(cryptography.x509, UnsupportedGeneralNameType);
 pyo3::import_exception!(cryptography.x509, InvalidVersion);
+pyo3::import_exception!(cryptography.x509.verification, VerificationError);
 
 pub(crate) fn create_submodule(py: pyo3::Python<'_>) -> pyo3::PyResult<&pyo3::prelude::PyModule> {
     let submod = pyo3::prelude::PyModule::new(py, "exceptions")?;

src/rust/src/x509/verify.rs

@@ -10,11 +10,14 @@ use cryptography_x509_validation::{
 };
 use pyo3::IntoPy;
 
-use crate::error::{CryptographyError, CryptographyResult};
 use crate::types;
 use crate::x509::certificate::Certificate as PyCertificate;
 use crate::x509::common::{datetime_now, datetime_to_py, py_to_datetime};
 use crate::x509::sign;
+use crate::{
+    error::{CryptographyError, CryptographyResult},
+    exceptions::VerificationError,
+};
 
 pub(crate) struct PyCryptoOps {}
 
@@ -105,7 +108,7 @@ impl PyServerVerifier {
         _leaf: &PyCertificate,
         _intermediates: &'p pyo3::types::PyList,
     ) -> CryptographyResult<Vec<PyCertificate>> {
-        Err(pyo3::exceptions::PyNotImplementedError::new_err("unimplemented").into())
+        Err(VerificationError::new_err("unimplemented").into())
     }
 }
 

tests/x509/test_verification.py

@@ -11,7 +11,11 @@
 
 from cryptography import x509
 from cryptography.x509.general_name import DNSName, IPAddress
-from cryptography.x509.verification import PolicyBuilder, Store
+from cryptography.x509.verification import (
+    PolicyBuilder,
+    Store,
+    VerificationError,
+)
 from tests.x509.test_x509 import _load_cert
 
 
@@ -116,5 +120,5 @@ def test_not_implemented(self):
             os.path.join("x509", "cryptography.io.pem"),
             x509.load_pem_x509_certificate,
         )
-        with pytest.raises(NotImplementedError):
+        with pytest.raises(VerificationError):
             verifier.verify(cert, [])