docs/x509: fix verification example (#10169)

* docs/x509: fix verification example

Signed-off-by: William Woodruff <william@trailofbits.com>

* x509/verification: doctest

Signed-off-by: William Woodruff <william@trailofbits.com>

---------

Signed-off-by: William Woodruff <william@trailofbits.com>

docs/x509/verification.rst

@@ -15,19 +15,74 @@ or chain building.
 Example usage, with `certifi <https://pypi.org/project/certifi/>`_ providing
 the root of trust:
 
-.. code-block:: python
+.. testsetup::
 
-    from cryptography.x509 import Certificate, DNSName, load_pem_x509_certificates
-    from cryptography.x509.verification import PolicyBuilder, Store
-    import certifi
+    from cryptography.x509 import load_pem_x509_certificate, load_pem_x509_certificates
+    from datetime import datetime
 
-    with open(certifi.where(), "rb") as pems:
-        store = Store(load_pem_x509_certificates(pems.read()))
+    peer = load_pem_x509_certificate(b"""
+    -----BEGIN CERTIFICATE-----
+    MIIDgTCCAwegAwIBAgISBJUzlK20QGqPf5xI0aoE8OIBMAoGCCqGSM49BAMDMDIx
+    CzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQDEwJF
+    MTAeFw0yMzExMjIyMDUyNDBaFw0yNDAyMjAyMDUyMzlaMBoxGDAWBgNVBAMTD2Ny
+    eXB0b2dyYXBoeS5pbzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAh2A0yuOByJ
+    lxK3ps5vbSOT6ZmvAlflGLn8kEseeodIAockm0ISTb/NGSpu/SY4ITefAOSaulKn
+    BzDgmqjGRKujggITMIICDzAOBgNVHQ8BAf8EBAMCB4AwHQYDVR0lBBYwFAYIKwYB
+    BQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFJu7f03HjjwJ
+    MU6rfwDBzxySTrs5MB8GA1UdIwQYMBaAFFrz7Sv8NsI3eblSMOpUb89Vyy6sMFUG
+    CCsGAQUFBwEBBEkwRzAhBggrBgEFBQcwAYYVaHR0cDovL2UxLm8ubGVuY3Iub3Jn
+    MCIGCCsGAQUFBzAChhZodHRwOi8vZTEuaS5sZW5jci5vcmcvMBoGA1UdEQQTMBGC
+    D2NyeXB0b2dyYXBoeS5pbzATBgNVHSAEDDAKMAgGBmeBDAECATCCAQYGCisGAQQB
+    1nkCBAIEgfcEgfQA8gB3AEiw42vapkc0D+VqAvqdMOscUgHLVt0sgdm7v6s52IRz
+    AAABi/kFXv4AAAQDAEgwRgIhAI9uF526YzU/DEfpmWRA28fn9gryrWMUCXQnEejQ
+    K/trAiEA12ePSql3sGJ/QgXc6ceQB/XAdwzwDB+2CHr6T14vvvUAdwDuzdBk1dsa
+    zsVct520zROiModGfLzs3sNRSFlGcR+1mwAAAYv5BV8kAAAEAwBIMEYCIQD1mqTn
+    b1hOpZWAUlwVM4EJLYA9HtlOvF70bfrGHpAX4gIhAI8pktDxrUwfTXPuA+eMFPbC
+    QraG6dMkB+HOmTz+hgKyMAoGCCqGSM49BAMDA2gAMGUCMQC+PwiHciKMaJyRJkGa
+    KFjT/1ICAUsCm8o5h4Xxm0LoOCJVggaXeamDEYnPWbxGETgCME5TJzLIDuF3z6vX
+    1SLZDdvHEHLKfOL8/h8KctkjLQ8OJycxwIc+zK+xexVoIuxRhA==
+    -----END CERTIFICATE-----
+    """
+    )
 
-    builder = PolicyBuilder().store(store)
-    verifier = builder().build_server_verifier(DNSName("cryptography.io"))
+    untrusted_intermediates = load_pem_x509_certificates(b"""
+    -----BEGIN CERTIFICATE-----
+    MIICxjCCAk2gAwIBAgIRALO93/inhFu86QOgQTWzSkUwCgYIKoZIzj0EAwMwTzEL
+    MAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2VhcmNo
+    IEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDIwHhcNMjAwOTA0MDAwMDAwWhcN
+    MjUwOTE1MTYwMDAwWjAyMQswCQYDVQQGEwJVUzEWMBQGA1UEChMNTGV0J3MgRW5j
+    cnlwdDELMAkGA1UEAxMCRTEwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAQkXC2iKv0c
+    S6Zdl3MnMayyoGli72XoprDwrEuf/xwLcA/TmC9N/A8AmzfwdAVXMpcuBe8qQyWj
+    +240JxP2T35p0wKZXuskR5LBJJvmsSGPwSSB/GjMH2m6WPUZIvd0xhajggEIMIIB
+    BDAOBgNVHQ8BAf8EBAMCAYYwHQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMB
+    MBIGA1UdEwEB/wQIMAYBAf8CAQAwHQYDVR0OBBYEFFrz7Sv8NsI3eblSMOpUb89V
+    yy6sMB8GA1UdIwQYMBaAFHxClq7eS0g7+pL4nozPbYupcjeVMDIGCCsGAQUFBwEB
+    BCYwJDAiBggrBgEFBQcwAoYWaHR0cDovL3gyLmkubGVuY3Iub3JnLzAnBgNVHR8E
+    IDAeMBygGqAYhhZodHRwOi8veDIuYy5sZW5jci5vcmcvMCIGA1UdIAQbMBkwCAYG
+    Z4EMAQIBMA0GCysGAQQBgt8TAQEBMAoGCCqGSM49BAMDA2cAMGQCMHt01VITjWH+
+    Dbo/AwCd89eYhNlXLr3pD5xcSAQh8suzYHKOl9YST8pE9kLJ03uGqQIwWrGxtO3q
+    YJkgsTgDyj2gJrjubi1K9sZmHzOa25JK1fUpE8ZwYii6I4zPPS/Lgul/
+    -----END CERTIFICATE-----
+    """)
 
-    chain = verifier.verify(peer, untrusted_intermediates)
+    verification_time = datetime.fromisoformat("2024-01-12T00:00:00Z")
+
+.. doctest::
+
+    >>> from cryptography.x509 import Certificate, DNSName, load_pem_x509_certificates
+    >>> from cryptography.x509.verification import PolicyBuilder, Store
+    >>> import certifi
+    >>> from datetime import datetime
+    >>> with open(certifi.where(), "rb") as pems:
+    ...    store = Store(load_pem_x509_certificates(pems.read()))
+    >>> builder = PolicyBuilder().store(store)
+    >>> builder = builder.time(verification_time)
+    >>> verifier = builder.build_server_verifier(DNSName("cryptography.io"))
+    >>> # NOTE: peer and untrusted_intermediates are Certificate and
+    >>> #       list[Certificate] respectively, and should be loaded from the
+    >>> #       application context that needs them verified, such as a
+    >>> #       TLS socket.
+    >>> chain = verifier.verify(peer, untrusted_intermediates)
 
 .. class:: Store(certs)