diff --git a/docs/x509/verification.rst b/docs/x509/verification.rst index c0d4c311e0f1..f46dd91c729b 100644 --- a/docs/x509/verification.rst +++ b/docs/x509/verification.rst @@ -21,3 +21,35 @@ chain building, etc. :param certs: A list of one or more :class:`~cryptography.x509.Certificate` instances. + +.. class:: Subject + + .. versionadded:: 42.0.0 + + Type alias: A union of all subject types supported: + :class:`cryptography.x509.general_name.DNSName`, + :class:`cryptography.x509.general_name.IPAddress`. + + +.. class:: PolicyBuilder + + .. versionadded:: 42.0.0 + + A PolicyBuilder provides a builder-style interface for constructing a + Verifier. + + .. method:: time(new_time) + + Sets the policy's verification time. + + :param new_time: The :class:`datetime.datetime` to use in the policy + + :returns: A new instance of :class:`PolicyBuilder` + + .. method:: build_server_verifier(subject) + + Builds a verifier for verifying server certificates. + + :param subject: A :class:`Subject` to use in the policy + + :raises NotImplementedError: This API is not implemented yet. diff --git a/src/cryptography/x509/verification.py b/src/cryptography/x509/verification.py index c622c47e2a2d..5274fab896a2 100644 --- a/src/cryptography/x509/verification.py +++ b/src/cryptography/x509/verification.py @@ -2,8 +2,43 @@ # 2.0, and the BSD License. See the LICENSE file in the root of this repository # for complete details. +from __future__ import annotations + +import datetime +import typing + from cryptography.hazmat.bindings._rust import x509 as rust_x509 +from cryptography.x509.general_name import DNSName, IPAddress -__all__ = ["Store"] +__all__ = ["Store", "Subject", "PolicyBuilder"] Store = rust_x509.Store + +Subject = typing.Union[DNSName, IPAddress] + + +class PolicyBuilder: + def __init__( + self, + *, + time: datetime.datetime | None = None, + ): + self._time = time + + def time(self, new_time: datetime.datetime) -> PolicyBuilder: + """ + Sets the validation time. + """ + if self._time is not None: + raise ValueError("The validation time may only be set once.") + + return PolicyBuilder( + time=new_time, + ) + + def build_server_verifier(self, subject: Subject) -> typing.NoReturn: + """ + Builds a verifier for verifying server certificates. + """ + + raise NotImplementedError diff --git a/tests/x509/test_verification.py b/tests/x509/test_verification.py index 8e8ad3b0900d..2d8e4a16c444 100644 --- a/tests/x509/test_verification.py +++ b/tests/x509/test_verification.py @@ -2,12 +2,14 @@ # 2.0, and the BSD License. See the LICENSE file in the root of this repository # for complete details. +import datetime import os import pytest from cryptography import x509 -from cryptography.x509.verification import Store +from cryptography.x509.general_name import DNSName +from cryptography.x509.verification import PolicyBuilder, Store from tests.x509.test_x509 import _load_cert @@ -26,3 +28,17 @@ def test_store_initializes(self): x509.load_pem_x509_certificate, ) assert Store([cert]) is not None + + +class TestPolicyBuilder: + def test_time_already_set(self): + with pytest.raises(ValueError): + PolicyBuilder().time(datetime.datetime.now()).time( + datetime.datetime.now() + ) + + def test_build_not_implemented(self): + with pytest.raises(NotImplementedError): + PolicyBuilder().time( + datetime.datetime.now() + ).build_server_verifier(DNSName("cryptography.io"))