diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 8cbe187e3e3f..a8be33e82d57 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..2887bcdfa9d0 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:: 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 @@ -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` + .. attribute:: policy - The verifier's subject. + :type: :class:`Policy` - .. 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. + The policy used by the verifier. Can be used to access verification time, chain depth, etc. .. attribute:: store @@ -276,6 +267,20 @@ the root of trust: :returns: A new instance of :class:`PolicyBuilder` + .. method:: extension_policies(new_ee_policy, new_ca_policy) + + .. versionadded:: 44.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` + 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. + + :returns: A new instance of :class:`PolicyBuilder` + + .. method:: build_server_verifier(subject) Builds a verifier for verifying server certificates. @@ -297,3 +302,171 @@ the root of trust: for server verification. :returns: An instance of :class:`ClientVerifier` + +.. class:: ExtensionPolicy + + .. versionadded:: 44.0.0 + + 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` + + .. staticmethod:: webpki_defaults_ca() + + 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:`ExtensionPolicy` + + .. staticmethod:: webpki_defaults_ee() + + 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:`ExtensionPolicy` + + .. method:: require_not_present(oid) + + 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. + + :returns: An instance of :class:`ExtensionPolicy` + + .. method:: may_be_present(oid, 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. + 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:`ExtensionPolicy` + + .. 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. + + 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:`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:: Policy + + .. versionadded:: 44.0.0 + + Represents a policy for certificate verification. Passed to extension validator callbacks and + accessible via :class:`ClientVerifier` and :class:`ServerVerifier`. + + .. 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.