verification: client verification APIs (#10345)

* verification: WIP client verification skeleton

Signed-off-by: William Woodruff <william@yossarian.net>

* verify: fill in build_client_verifier

Signed-off-by: William Woodruff <william@yossarian.net>

* implement ClientVerifier.verify

Signed-off-by: William Woodruff <william@yossarian.net>

* verification: make Python 3.8 happy

Signed-off-by: William Woodruff <william@yossarian.net>

* switch to a full VerifiedClient type

Signed-off-by: William Woodruff <william@yossarian.net>

* remove the SubjectOwner::None hack

Signed-off-by: William Woodruff <william@yossarian.net>

* docs: fix ClientVerifier

Signed-off-by: William Woodruff <william@yossarian.net>

* verification: replace match with if

Signed-off-by: William Woodruff <william@yossarian.net>

* return GNs directly, not whole extension

Signed-off-by: William Woodruff <william@yossarian.net>

* docs/verification: document UnsupportedGeneralNameType raise

Signed-off-by: William Woodruff <william@yossarian.net>

* lib: RFC822 checks on NCs

* test_limbo: enable client tests

* tests: flake

* test_verification: more Python API coverage

* verification: filter GNs by NC support

* verification: forbid unsupported NC GNs

This is what we should have been doing originally, per
RFC 5280 4.2.1.10:

> If a name constraints extension that is marked as critical
> imposes constraints on a particular name form, and an instance of
> that name form appears in the subject field or subjectAltName
> extension of a subsequent certificate, then the application MUST
> either process the constraint or reject the certificate.

* docs/verification: remove old sentence

Signed-off-by: William Woodruff <william@yossarian.net>

* verification: ensure the right EKU for client/server paths

Signed-off-by: William Woodruff <william@yossarian.net>

* test_limbo: fixup EKU assertion

* verification: feedback

---------

Signed-off-by: William Woodruff <william@yossarian.net>

1 files changed, 83 insertions, 1 deletions

diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst
index 6afc75f..ab36041 100644
--- a/docs/x509/verification.rst
+++ b/docs/x509/verification.rst
@@ -104,6 +104,73 @@ the root of trust:
     :class:`cryptography.x509.general_name.DNSName`,
     :class:`cryptography.x509.general_name.IPAddress`.
 
+.. class:: VerifiedClient
+
+    .. versionadded:: 43.0.0
+
+    .. attribute:: subjects
+
+        :type: list of :class:`~cryptography.x509.GeneralName`
+
+        The subjects presented in the verified client's Subject Alternative Name
+        extension.
+
+    .. attribute:: chain
+
+        :type: A list of :class:`~cryptography.x509.Certificate`, in leaf-first order
+
+        The chain of certificates that forms the valid chain to the client
+        certificate.
+
+
+.. class:: ClientVerifier
+
+    .. versionadded:: 43.0.0
+
+    A ClientVerifier verifies client certificates.
+
+    It contains and describes various pieces of configurable path
+    validation logic, such as how deep prospective validation chains may go,
+    which signature algorithms are allowed, and so forth.
+
+    ClientVerifier instances cannot be constructed directly;
+    :class:`PolicyBuilder` must be used.
+
+    .. attribute:: validation_time
+
+        :type: :class:`datetime.datetime`
+
+        The verifier's validation time.
+
+    .. attribute:: max_chain_depth
+
+        :type: :class:`int`
+
+        The verifier's maximum intermediate CA chain depth.
+
+    .. attribute:: store
+
+        :type: :class:`Store`
+
+        The verifier's trust store.
+
+    .. 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 new instance of :class:`VerifiedClient`
+
+        :raises VerificationError: If a valid chain cannot be constructed
+
+        :raises UnsupportedGeneralNameType: If a valid chain exists, but contains an unsupported general name type
+
 .. class:: ServerVerifier
 
     .. versionadded:: 42.0.0
@@ -174,7 +241,8 @@ the root of trust:
         Sets the verifier's verification time.
 
         If not called explicitly, this is set to :meth:`datetime.datetime.now`
-        when :meth:`build_server_verifier` is called.
+        when :meth:`build_server_verifier` or :meth:`build_client_verifier`
+        is called.
 
         :param new_time: The :class:`datetime.datetime` to use in the verifier
 
@@ -209,3 +277,17 @@ the root of trust:
         :param subject: A :class:`Subject` to use in the verifier
 
         :returns: An instance of :class:`ServerVerifier`
+
+    .. method:: build_client_verifier()
+
+        .. versionadded:: 43.0.0
+
+        Builds a verifier for verifying client certificates.
+
+        .. warning::
+
+            This API is not suitable for website (i.e. server) certificate
+            verification. You **must** use :meth:`build_server_verifier`
+            for server verification.
+
+        :returns: An instance of :class:`ClientVerifier`