docs: add Store docs (#9416)

* docs: add Store docs

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

* src, tests: don't allow empty stores

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

* Update docs/x509/verification.rst

Co-authored-by: Alex Gaynor <[email protected]>

---------

Signed-off-by: William Woodruff <[email protected]>
Co-authored-by: Alex Gaynor <[email protected]>

Author: woodruffw

docs/x509/index.rst

@@ -11,6 +11,7 @@ certificates are commonly used in protocols like `TLS`_.
     tutorial
     certificate-transparency
     ocsp
+    verification
     reference
 
 .. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure

docs/x509/verification.rst

@@ -0,0 +1,23 @@
+X.509 verification
+==================
+
+.. currentmodule:: cryptography.x509.verification
+
+Support for X.509 certificate verification, also known as path validation,
+chain building, etc.
+
+.. note::
+    This module is a work in progress, and does not yet contain a fully usable
+    X.509 path validation implementation.
+
+.. class:: Store(certs)
+
+    .. versionadded:: 42.0.0
+
+    A Store is an opaque set of public keys and subject identifiers that are
+    considered trusted *a priori*. Stores are typically created from the host
+    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`
+        instances.

src/rust/src/x509/verify.rs

@@ -15,6 +15,11 @@ struct PyStore(Vec<pyo3::Py<PyCertificate>>);
 impl PyStore {
     #[new]
     fn new(certs: Vec<pyo3::Py<PyCertificate>>) -> pyo3::PyResult<Self> {
+        if certs.is_empty() {
+            return Err(pyo3::exceptions::PyValueError::new_err(
+                "can't create an empty store",
+            ));
+        }
         Ok(Self(certs))
     }
 }

tests/x509/test_verification.py

@@ -12,6 +12,10 @@
 
 
 class TestStore:
+    def test_store_rejects_empty_list(self):
+        with pytest.raises(ValueError):
+            Store([])
+
     def test_store_rejects_non_certificates(self):
         with pytest.raises(TypeError):
             Store(["not a cert"])  # type: ignore[list-item]