From 4a3e7dcc977cc3f9091154c15e6ecdcee3b1d00d Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Wed, 20 Mar 2024 21:00:00 -0400 Subject: verification: client verification APIs (#10345) * verification: WIP client verification skeleton Signed-off-by: William Woodruff * verify: fill in build_client_verifier Signed-off-by: William Woodruff * implement ClientVerifier.verify Signed-off-by: William Woodruff * verification: make Python 3.8 happy Signed-off-by: William Woodruff * switch to a full VerifiedClient type Signed-off-by: William Woodruff * remove the SubjectOwner::None hack Signed-off-by: William Woodruff * docs: fix ClientVerifier Signed-off-by: William Woodruff * verification: replace match with if Signed-off-by: William Woodruff * return GNs directly, not whole extension Signed-off-by: William Woodruff * docs/verification: document UnsupportedGeneralNameType raise Signed-off-by: William Woodruff * 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 * verification: ensure the right EKU for client/server paths Signed-off-by: William Woodruff * test_limbo: fixup EKU assertion * verification: feedback --------- Signed-off-by: William Woodruff --- docs/x509/verification.rst | 84 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) (limited to 'docs') 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` -- cgit v1.1