From 89cc062d7c1a5f10275ab303a7fc7b22acc067bf Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Sat, 19 Oct 2024 12:00:44 +0200 Subject: [PATCH 01/12] Add docs related to custom x509 verification extension policies. --- docs/spelling_wordlist.txt | 1 + docs/x509/verification.rst | 205 +++++++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+) diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 7e50a1f814be..001f8f5f7c2a 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -28,6 +28,7 @@ committers conda CPython Cryptanalysis +criticalities crypto cryptographic cryptographically diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index 70aafd48f94c..1d0e37307fe7 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -276,6 +276,32 @@ the root of trust: :returns: A new instance of :class:`PolicyBuilder` + .. method:: ca_extension_policy(new_policy) + + .. versionadded:: 44.0.0 + + Sets the CA extension policy for the verifier. + If this method is not called, the default CA extension policy that + follows the CA/B Forum guidelines is used. + + :param ExtensionPolicy new_policy: The CA extension policy to use. + Use :class:`ExtensionPolicyBuilder` to create the policy. + + :returns: A new instance of :class:`PolicyBuilder` + + .. method:: ee_extension_policy(new_policy) + + .. versionadded:: 44.0.0 + + Sets the End Entity (EE) extension policy for the verifier. + If this method is not called, the default EE extension policy that + follows the CA/B Forum guidelines is used. + + :param ExtensionPolicy new_policy: The EE extension policy to use. + Use :class:`ExtensionPolicyBuilder` to create the policy. + + :returns: A new instance of :class:`PolicyBuilder` + .. method:: build_server_verifier(subject) Builds a verifier for verifying server certificates. @@ -297,3 +323,182 @@ the root of trust: for server verification. :returns: An instance of :class:`ClientVerifier` + +.. class:: ExtensionPolicyBuilder + + .. versionadded:: 44.0.0 + + An ExtensionPolicyBuilder provides a builder-style interface for constructing an + :class:`ExtensionPolicy`. + + .. staticmethod:: permit_all() + + Creates an ExtensionPolicyBuilder initialized with a policy that does + not put any constraints on a certificate's extensions. + + :returns: An instance of :class:`ExtensionPolicyBuilder` + + .. staticmethod:: webpki_defaults_ca() + + Creates an ExtensionPolicyBuilder initialized with a + CA extension policy based on CA/B Forum guidelines. + + This is the CA extension policy used by :class:`PolicyBuilder`. + + :returns: An instance of :class:`ExtensionPolicyBuilder` + + .. staticmethod:: webpki_defaults_ee() + + Creates an ExtensionPolicyBuilder initialized with an + EE extension policy based on CA/B Forum guidelines. + + This is the EE extension policy used by :class:`PolicyBuilder`. + + :returns: An instance of :class:`ExtensionPolicyBuilder` + + .. method:: not_present(oid) + + Specifies that the extension identified by the given OID must not be present. + + :param oid: The OID of the extension that must not be present. + + :returns: An instance of :class:`ExtensionPolicyBuilder` + + .. method:: maybe_present(oid, criticality, validator_cb) + + Specifies that the extension identified by the given OID may or may not be present. + If it is present, it must conform to the given criticality constraint. + An optional validator callback may be provided. + + If a validator callback is provided, the callback will be invoked + when :meth:`ClientVerifier.verify` or :meth:`ServerVerifier.verify` is called on a verifier + that uses the extension policy. For details on the callback signature, see :type:`MaybeExtensionValidatorCallback`. + + :param ObjectIdentifier oid: The OID of the extension that may be present + :param Criticality criticality: The criticality of the extension + :param validator_cb: An optional Python callback to validate the extension value. + :type validator_cb: :type:`MaybeExtensionValidatorCallback` or None + + :returns: An instance of :class:`ExtensionPolicyBuilder` + + .. method:: must_be_present(oid, criticality, validator_cb) + + Specifies that the extension identified by the given OID must be present and conform to the given criticality constraint. + An optional validator callback may be provided. + + If a validator callback is provided, the callback will be invoked + when :meth:`ClientVerifier.verify` or :meth:`ServerVerifier.verify` is called on a verifier + that uses the extension policy. For details on the callback signature, see :type:`PresentExtensionValidatorCallback`. + + :param ObjectIdentifier oid: The OID of the extension that must be present + :param Criticality criticality: The criticality of the extension + :param validator_cb: An optional Python callback to validate the extension + :type validator_cb: :type:`PresentExtensionValidatorCallback` or None + + :returns: An instance of :class:`ExtensionPolicyBuilder` + + .. method:: build() + + Builds the extension policy. + + :returns: An :class:`ExtensionPolicy` + +.. class:: Criticality + + .. versionadded:: 44.0.0 + + An enumeration of criticality constraints for certificate extensions. + + .. attribute:: CRITICAL + + The extension must be marked as critical. + + .. attribute:: AGNOSTIC + + The extension may be marked either as critical or non-critical. + + .. attribute:: NON_CRITICAL + + The extension must not be marked as critical. + +.. class:: ExtensionPolicy + + .. versionadded:: 44.0.0 + + An ExtensionPolicy constrains the presence, contents and criticalities of certificate extensions. + + This type is opaque to the user and should be created using :class:`ExtensionPolicyBuilder`. + Pass the created policy to :meth:`PolicyBuilder.ca_extension_policy` or :meth:`PolicyBuilder.ee_extension_policy` + to set the policies used during verification. + +.. class:: Policy + + .. versionadded:: 44.0.0 + + Represents a policy for certificate verification. Passed to extension validator callbacks. + + .. attribute:: max_chain_depth + + The maximum chain depth (as described in :meth:`PolicyBuilder.max_chain_depth`). + + :type: int + + .. attribute:: subject + + The subject used during verification. + Will be None if the verifier is a :class:`ClientVerifier`. + + :type: x509.verification.Subject or None + + .. attribute:: validation_time + + The validation time. + + :type: datetime.datetime + + .. attribute:: extended_key_usage + + The Extended Key Usage required by the policy. + + :type: x509.ObjectIdentifier + + .. attribute:: minimum_rsa_modulus + + The minimum RSA modulus size required by the policy. + + :type: int + +.. type:: MaybeExtensionValidatorCallback + :canonical: Callable[[Policy, Certificate, Optional[ExtensionType]], None] + + .. versionadded:: 44.0.0 + + + A Python callback that validates an extension that may or may not be present. + If the extension is not present, the callback will be invoked with `ext` set to `None`. + + To fail the validation, the callback must raise an exception. + + :param Policy policy: The verification policy. + :param Certificate certificate: The certificate being verified. + :param ExtensionType or None extension: The extension value or `None` if the extension is not present. + + :returns: An extension validator callback must return `None`. + If the validation fails, the validator must raise an exception. + +.. type:: PresentExtensionValidatorCallback + :canonical: Callable[[Policy, Certificate, ExtensionType], None] + + .. versionadded:: 44.0.0 + + + A Python callback that validates an extension that must be present. + + To fail the validation, the callback must raise an exception. + + :param Policy policy: The verification policy. + :param Certificate certificate: The certificate being verified. + :param ExtensionType extension: The extension value. + + :returns: An extension validator callback must return `None`. + If the validation fails, the validator must raise an exception. From ecaeec0f67f23d0e155d063399ff5184393ed68f Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Sat, 26 Oct 2024 15:26:34 +0200 Subject: [PATCH 02/12] Improve naming of extension policy builder methods. --- docs/x509/verification.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index 1d0e37307fe7..3a1d2e453644 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -356,7 +356,7 @@ the root of trust: :returns: An instance of :class:`ExtensionPolicyBuilder` - .. method:: not_present(oid) + .. method:: require_not_present(oid) Specifies that the extension identified by the given OID must not be present. @@ -364,7 +364,7 @@ the root of trust: :returns: An instance of :class:`ExtensionPolicyBuilder` - .. method:: maybe_present(oid, criticality, validator_cb) + .. method:: may_be_present(oid, criticality, validator_cb) Specifies that the extension identified by the given OID may or may not be present. If it is present, it must conform to the given criticality constraint. @@ -381,7 +381,7 @@ the root of trust: :returns: An instance of :class:`ExtensionPolicyBuilder` - .. method:: must_be_present(oid, criticality, validator_cb) + .. method:: require_present(oid, criticality, validator_cb) Specifies that the extension identified by the given OID must be present and conform to the given criticality constraint. An optional validator callback may be provided. From 02d94d67399454eca13b5f112f41e913b73ec5c5 Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Sat, 26 Oct 2024 15:42:54 +0200 Subject: [PATCH 03/12] Use single method to set both extension policies. --- docs/x509/verification.rst | 62 +++++++++++--------------------------- 1 file changed, 17 insertions(+), 45 deletions(-) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index 3a1d2e453644..d991bce74c43 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -276,31 +276,19 @@ the root of trust: :returns: A new instance of :class:`PolicyBuilder` - .. method:: ca_extension_policy(new_policy) + .. method:: extension_policies(new_ee_policy, new_ca_policy) .. versionadded:: 44.0.0 - Sets the CA extension policy for the verifier. - If this method is not called, the default CA extension policy that - follows the CA/B Forum guidelines is used. + Sets the EE and CA extension policies for the verifier. + The default policies used are those returned by :meth:`ExtensionPolicy.webpki_defaults_ee` + and :meth:`ExtensionPolicy.webpki_defaults_ca`. - :param ExtensionPolicy new_policy: The CA extension policy to use. - Use :class:`ExtensionPolicyBuilder` to create the policy. + :param ExtensionPolicy new_ee_policy: The CA extension policy to use. + :param ExtensionPolicy new_ca_policy: The EE extension policy to use. :returns: A new instance of :class:`PolicyBuilder` - .. method:: ee_extension_policy(new_policy) - - .. versionadded:: 44.0.0 - - Sets the End Entity (EE) extension policy for the verifier. - If this method is not called, the default EE extension policy that - follows the CA/B Forum guidelines is used. - - :param ExtensionPolicy new_policy: The EE extension policy to use. - Use :class:`ExtensionPolicyBuilder` to create the policy. - - :returns: A new instance of :class:`PolicyBuilder` .. method:: build_server_verifier(subject) @@ -324,37 +312,37 @@ the root of trust: :returns: An instance of :class:`ClientVerifier` -.. class:: ExtensionPolicyBuilder +.. class:: ExtensionPolicy .. versionadded:: 44.0.0 - An ExtensionPolicyBuilder provides a builder-style interface for constructing an + An ExtensionPolicy provides a builder-style interface for constructing an :class:`ExtensionPolicy`. .. staticmethod:: permit_all() - Creates an ExtensionPolicyBuilder initialized with a policy that does + Creates an ExtensionPolicy initialized with a policy that does not put any constraints on a certificate's extensions. - :returns: An instance of :class:`ExtensionPolicyBuilder` + :returns: An instance of :class:`ExtensionPolicy` .. staticmethod:: webpki_defaults_ca() - Creates an ExtensionPolicyBuilder initialized with a + Creates an ExtensionPolicy initialized with a CA extension policy based on CA/B Forum guidelines. This is the CA extension policy used by :class:`PolicyBuilder`. - :returns: An instance of :class:`ExtensionPolicyBuilder` + :returns: An instance of :class:`ExtensionPolicy` .. staticmethod:: webpki_defaults_ee() - Creates an ExtensionPolicyBuilder initialized with an + Creates an ExtensionPolicy initialized with an EE extension policy based on CA/B Forum guidelines. This is the EE extension policy used by :class:`PolicyBuilder`. - :returns: An instance of :class:`ExtensionPolicyBuilder` + :returns: An instance of :class:`ExtensionPolicy` .. method:: require_not_present(oid) @@ -362,7 +350,7 @@ the root of trust: :param oid: The OID of the extension that must not be present. - :returns: An instance of :class:`ExtensionPolicyBuilder` + :returns: An instance of :class:`ExtensionPolicy` .. method:: may_be_present(oid, criticality, validator_cb) @@ -379,7 +367,7 @@ the root of trust: :param validator_cb: An optional Python callback to validate the extension value. :type validator_cb: :type:`MaybeExtensionValidatorCallback` or None - :returns: An instance of :class:`ExtensionPolicyBuilder` + :returns: An instance of :class:`ExtensionPolicy` .. method:: require_present(oid, criticality, validator_cb) @@ -395,13 +383,7 @@ the root of trust: :param validator_cb: An optional Python callback to validate the extension :type validator_cb: :type:`PresentExtensionValidatorCallback` or None - :returns: An instance of :class:`ExtensionPolicyBuilder` - - .. method:: build() - - Builds the extension policy. - - :returns: An :class:`ExtensionPolicy` + :returns: An instance of :class:`ExtensionPolicy` .. class:: Criticality @@ -421,16 +403,6 @@ the root of trust: The extension must not be marked as critical. -.. class:: ExtensionPolicy - - .. versionadded:: 44.0.0 - - An ExtensionPolicy constrains the presence, contents and criticalities of certificate extensions. - - This type is opaque to the user and should be created using :class:`ExtensionPolicyBuilder`. - Pass the created policy to :meth:`PolicyBuilder.ca_extension_policy` or :meth:`PolicyBuilder.ee_extension_policy` - to set the policies used during verification. - .. class:: Policy .. versionadded:: 44.0.0 From 5d2abf1620f9f7471eb8caa6a835d6664de65a25 Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Sat, 9 Nov 2024 09:47:16 +0100 Subject: [PATCH 04/12] Slight adjustment to ExtensionPolicy documentation to use x509 spec terms. --- docs/x509/verification.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index d991bce74c43..7199c511c1f7 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -346,7 +346,7 @@ the root of trust: .. method:: require_not_present(oid) - Specifies that the extension identified by the given OID must not be present. + Specifies that the extension identified by the given OID must not be present (must be absent). :param oid: The OID of the extension that must not be present. @@ -354,7 +354,7 @@ the root of trust: .. method:: may_be_present(oid, criticality, validator_cb) - Specifies that the extension identified by the given OID may or may not be present. + Specifies that the extension identified by the given OID is optional. If it is present, it must conform to the given criticality constraint. An optional validator callback may be provided. From c46987f8fc2dea5791f41608ef63aefd2c99750e Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Mon, 11 Nov 2024 10:50:43 +0100 Subject: [PATCH 05/12] Replace some fields on [Client|Server]Verifier with `policy` property. (docs) --- docs/x509/verification.rst | 42 +++++++++++++++----------------------- 1 file changed, 17 insertions(+), 25 deletions(-) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index 7199c511c1f7..9e34f5c39b50 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -133,6 +133,10 @@ the root of trust: .. versionadded:: 43.0.0 + .. versionchanged:: 44.0.0 + ``verification_time`` and ``max_chain_depth`` were replaced by the + ``policy`` property that provides access to these values. + A ClientVerifier verifies client certificates. It contains and describes various pieces of configurable path @@ -142,17 +146,11 @@ the root of trust: ClientVerifier instances cannot be constructed directly; :class:`PolicyBuilder` must be used. - .. attribute:: validation_time - - :type: :class:`datetime.datetime` - - The verifier's validation time. + .. attribute:: policy - .. attribute:: max_chain_depth - - :type: :class:`int` + :type: :class:`Policy` - The verifier's maximum intermediate CA chain depth. + The policy used by the verifier. Can be used to access verification time, chain depth, etc. .. attribute:: store @@ -181,6 +179,11 @@ the root of trust: .. versionadded:: 42.0.0 + .. versionchanged:: 44.0.0 + ``subject``, ``verification_time`` and ``max_chain_depth`` were replaced by the + ``policy`` property that provides access to these values. + + A ServerVerifier verifies server certificates. It contains and describes various pieces of configurable path @@ -191,23 +194,11 @@ the root of trust: 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. - - .. attribute:: max_chain_depth + .. attribute:: policy - :type: :class:`int` + :type: :class:`Policy` - The verifier's maximum intermediate CA chain depth. + The policy used by the verifier. Can be used to access verification time, chain depth, etc. .. attribute:: store @@ -407,7 +398,8 @@ the root of trust: .. versionadded:: 44.0.0 - Represents a policy for certificate verification. Passed to extension validator callbacks. + Represents a policy for certificate verification. Passed to extension validator callbacks and + accessible via :class:`ClientVerifier` and :class:`ServerVerifier`. .. attribute:: max_chain_depth From cbab0a371cc618577ee355cfb5363e66cfa5ca5d Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Mon, 9 Dec 2024 09:40:29 +0100 Subject: [PATCH 06/12] Doc updates per PR discussion. --- docs/x509/verification.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index 9e34f5c39b50..2887bcdfa9d0 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -307,13 +307,17 @@ the root of trust: .. versionadded:: 44.0.0 - An ExtensionPolicy provides a builder-style interface for constructing an - :class:`ExtensionPolicy`. + ExtensionPolicy provides a set of static methods to construct predefined + extension policies, and a builder-style interface for modifying them. + + .. note:: Calling any of the builder methods (:meth:`require_not_present`, :meth:`may_be_present`, or :meth:`require_present`) + multiple times with the same extension OID will raise an exception. .. staticmethod:: permit_all() Creates an ExtensionPolicy initialized with a policy that does not put any constraints on a certificate's extensions. + This can serve as a base for a fully custom extension policy. :returns: An instance of :class:`ExtensionPolicy` From 26bf5a81a472ebf1f3d1062174e4b61c7360036a Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Thu, 13 Feb 2025 08:59:36 +0100 Subject: [PATCH 07/12] Update versionadded to 45. --- docs/x509/verification.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index 2887bcdfa9d0..f4bcba06279d 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -111,7 +111,7 @@ the root of trust: .. versionadded:: 43.0.0 - .. versionchanged:: 44.0.0 + .. versionchanged:: 45.0.0 Made ``subjects`` optional with the addition of custom extension policies. .. attribute:: subjects @@ -133,7 +133,7 @@ the root of trust: .. versionadded:: 43.0.0 - .. versionchanged:: 44.0.0 + .. versionchanged:: 45.0.0 ``verification_time`` and ``max_chain_depth`` were replaced by the ``policy`` property that provides access to these values. @@ -179,7 +179,7 @@ the root of trust: .. versionadded:: 42.0.0 - .. versionchanged:: 44.0.0 + .. versionchanged:: 45.0.0 ``subject``, ``verification_time`` and ``max_chain_depth`` were replaced by the ``policy`` property that provides access to these values. @@ -269,7 +269,7 @@ the root of trust: .. method:: extension_policies(new_ee_policy, new_ca_policy) - .. versionadded:: 44.0.0 + .. versionadded:: 45.0.0 Sets the EE and CA extension policies for the verifier. The default policies used are those returned by :meth:`ExtensionPolicy.webpki_defaults_ee` @@ -305,7 +305,7 @@ the root of trust: .. class:: ExtensionPolicy - .. versionadded:: 44.0.0 + .. versionadded:: 45.0.0 ExtensionPolicy provides a set of static methods to construct predefined extension policies, and a builder-style interface for modifying them. @@ -382,7 +382,7 @@ the root of trust: .. class:: Criticality - .. versionadded:: 44.0.0 + .. versionadded:: 45.0.0 An enumeration of criticality constraints for certificate extensions. @@ -400,7 +400,7 @@ the root of trust: .. class:: Policy - .. versionadded:: 44.0.0 + .. versionadded:: 45.0.0 Represents a policy for certificate verification. Passed to extension validator callbacks and accessible via :class:`ClientVerifier` and :class:`ServerVerifier`. @@ -439,7 +439,7 @@ the root of trust: .. type:: MaybeExtensionValidatorCallback :canonical: Callable[[Policy, Certificate, Optional[ExtensionType]], None] - .. versionadded:: 44.0.0 + .. versionadded:: 45.0.0 A Python callback that validates an extension that may or may not be present. @@ -457,7 +457,7 @@ the root of trust: .. type:: PresentExtensionValidatorCallback :canonical: Callable[[Policy, Certificate, ExtensionType], None] - .. versionadded:: 44.0.0 + .. versionadded:: 45.0.0 A Python callback that validates an extension that must be present. From a5d4bbca3ebf4c702e3900ec24f3588a01f661f8 Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Thu, 13 Feb 2025 09:01:57 +0100 Subject: [PATCH 08/12] Correct order of ca and ee policy args. --- docs/x509/verification.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index f4bcba06279d..51763e4c38c5 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -275,8 +275,8 @@ the root of trust: The default policies used are those returned by :meth:`ExtensionPolicy.webpki_defaults_ee` and :meth:`ExtensionPolicy.webpki_defaults_ca`. - :param ExtensionPolicy new_ee_policy: The CA extension policy to use. - :param ExtensionPolicy new_ca_policy: The EE extension policy to use. + :param ExtensionPolicy new_ca_policy: The CA extension policy to use. + :param ExtensionPolicy new_ee_policy: The EE extension policy to use. :returns: A new instance of :class:`PolicyBuilder` From 1f6c27c5ed59fb6039deca05459fe38816e4a7c5 Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Thu, 13 Feb 2025 09:59:30 +0100 Subject: [PATCH 09/12] Update docs to reflect ExtensionPolicy API changes. --- docs/x509/verification.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index 51763e4c38c5..aa0d63b45883 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -347,7 +347,7 @@ the root of trust: :returns: An instance of :class:`ExtensionPolicy` - .. method:: may_be_present(oid, criticality, validator_cb) + .. method:: may_be_present(extension_type, criticality, validator_cb) Specifies that the extension identified by the given OID is optional. If it is present, it must conform to the given criticality constraint. @@ -357,14 +357,16 @@ the root of trust: when :meth:`ClientVerifier.verify` or :meth:`ServerVerifier.verify` is called on a verifier that uses the extension policy. For details on the callback signature, see :type:`MaybeExtensionValidatorCallback`. - :param ObjectIdentifier oid: The OID of the extension that may be present + :param type[ExtensionType] extension_type: A concrete class derived from :type:`~cryptography.x509.ExtensionType` + indicating which extension may be present. :param Criticality criticality: The criticality of the extension :param validator_cb: An optional Python callback to validate the extension value. + Must accept extensions of type `extension_type`. :type validator_cb: :type:`MaybeExtensionValidatorCallback` or None :returns: An instance of :class:`ExtensionPolicy` - .. method:: require_present(oid, criticality, validator_cb) + .. method:: require_present(extension_type, criticality, validator_cb) Specifies that the extension identified by the given OID must be present and conform to the given criticality constraint. An optional validator callback may be provided. @@ -373,9 +375,11 @@ the root of trust: when :meth:`ClientVerifier.verify` or :meth:`ServerVerifier.verify` is called on a verifier that uses the extension policy. For details on the callback signature, see :type:`PresentExtensionValidatorCallback`. - :param ObjectIdentifier oid: The OID of the extension that must be present + :param type[ExtensionType] extension_type: A concrete class derived from :type:`~cryptography.x509.ExtensionType` + indicating which extension is required to be present. :param Criticality criticality: The criticality of the extension - :param validator_cb: An optional Python callback to validate the extension + :param validator_cb: An optional Python callback to validate the extension value. + Must accept extensions of type `extension_type`. :type validator_cb: :type:`PresentExtensionValidatorCallback` or None :returns: An instance of :class:`ExtensionPolicy` From dd04a829ad0f84e9a5a5faeb4e03ab0608709c4a Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Thu, 13 Feb 2025 10:23:49 +0100 Subject: [PATCH 10/12] Fix remnants from previous API iteration. --- docs/x509/verification.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index aa0d63b45883..1c37e1d879ff 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -311,7 +311,7 @@ the root of trust: extension policies, and a builder-style interface for modifying them. .. note:: Calling any of the builder methods (:meth:`require_not_present`, :meth:`may_be_present`, or :meth:`require_present`) - multiple times with the same extension OID will raise an exception. + multiple times with the same extension type will raise an exception. .. staticmethod:: permit_all() @@ -339,17 +339,17 @@ the root of trust: :returns: An instance of :class:`ExtensionPolicy` - .. method:: require_not_present(oid) + .. method:: require_not_present(extension_type) - Specifies that the extension identified by the given OID must not be present (must be absent). + Specifies that the extension identified by `extension_type` must not be present (must be absent). - :param oid: The OID of the extension that must not be present. + :param type[ExtensionType] extension_type: The extension_type of the extension that must not be present. :returns: An instance of :class:`ExtensionPolicy` .. method:: may_be_present(extension_type, criticality, validator_cb) - Specifies that the extension identified by the given OID is optional. + Specifies that the extension identified by `extension_type` is optional. If it is present, it must conform to the given criticality constraint. An optional validator callback may be provided. @@ -368,8 +368,8 @@ the root of trust: .. method:: require_present(extension_type, criticality, validator_cb) - Specifies that the extension identified by the given OID must be present and conform to the given criticality constraint. - An optional validator callback may be provided. + Specifies that the extension identified by `extension_type`` must be present + and conform to the given criticality constraint. An optional validator callback may be provided. If a validator callback is provided, the callback will be invoked when :meth:`ClientVerifier.verify` or :meth:`ServerVerifier.verify` is called on a verifier From 5caf1cbcf327fe6446da25088bdd6cd244ed3001 Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Thu, 13 Feb 2025 10:30:26 +0100 Subject: [PATCH 11/12] Reflect that properties were deprecated not removed in favor of policy property. --- docs/x509/verification.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index 1c37e1d879ff..77518598441d 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -134,8 +134,9 @@ the root of trust: .. versionadded:: 43.0.0 .. versionchanged:: 45.0.0 - ``verification_time`` and ``max_chain_depth`` were replaced by the - ``policy`` property that provides access to these values. + ``verification_time`` and ``max_chain_depth`` were deprecated and will be + removed in version 46.0.0. + The new ``policy`` property should be used to access these values instead. A ClientVerifier verifies client certificates. @@ -150,7 +151,7 @@ the root of trust: :type: :class:`Policy` - The policy used by the verifier. Can be used to access verification time, chain depth, etc. + The policy used by the verifier. Can be used to access verification time, maximum chain depth, etc. .. attribute:: store @@ -180,8 +181,9 @@ the root of trust: .. versionadded:: 42.0.0 .. versionchanged:: 45.0.0 - ``subject``, ``verification_time`` and ``max_chain_depth`` were replaced by the - ``policy`` property that provides access to these values. + ``subject``, ``verification_time`` and ``max_chain_depth`` were deprecated and will be + removed in version 46.0.0. + The new ``policy`` property should be used to access these values instead. A ServerVerifier verifies server certificates. @@ -198,7 +200,7 @@ the root of trust: :type: :class:`Policy` - The policy used by the verifier. Can be used to access verification time, chain depth, etc. + The policy used by the verifier. Can be used to access verification time, maximum chain depth, etc. .. attribute:: store From 0b112d4b4cc58f9497762cc9dfc874b08a54a43d Mon Sep 17 00:00:00 2001 From: Ivan Desiatov Date: Fri, 14 Feb 2025 15:50:04 +0100 Subject: [PATCH 12/12] Document which extension types are supported by ExtensionPolicy. --- docs/x509/verification.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index 77518598441d..e008ebc957ca 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -315,6 +315,16 @@ the root of trust: .. note:: Calling any of the builder methods (:meth:`require_not_present`, :meth:`may_be_present`, or :meth:`require_present`) multiple times with the same extension type will raise an exception. + .. note:: Currently only the following extension types are supported in the ExtensionPolicy API: + :class:`~cryptography.x509.AuthorityInformationAccess`, + :class:`~cryptography.x509.AuthorityKeyIdentifier`, + :class:`~cryptography.x509.SubjectKeyIdentifier`, + :class:`~cryptography.x509.KeyUsage`, + :class:`~cryptography.x509.SubjectAlternativeName`, + :class:`~cryptography.x509.BasicConstraints`, + :class:`~cryptography.x509.NameConstraints`, + :class:`~cryptography.x509.ExtendedKeyUsage`. + .. staticmethod:: permit_all() Creates an ExtensionPolicy initialized with a policy that does