move x509 to top level, add more docs

6 files changed, 208 insertions, 6 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 083533c9..918b43ac 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -67,6 +67,7 @@ The recipes layer
     exceptions
     faq
     glossary
+    x509
 
 The hazardous materials layer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/x509.rst b/docs/x509.rst
new file mode 100644
index 00000000..5d18297a
--- /dev/null
+++ b/docs/x509.rst
@@ -0,0 +1,97 @@
+.. hazmat::
+
+X.509
+=====
+
+.. currentmodule:: cryptography.hazmat.primitives.x509
+
+X.509 is an ITU-T standard for a `public key infrastructure`_. X.509v3 is
+defined in :rfc:`5280` (which obsoletes :rfc:`2459` and :rfc:`3280`).
+
+Loading
+~~~~~~~
+
+.. function:: load_pem_x509_certificate(data, backend)
+
+    .. versionadded:: 0.7
+
+    Deserialize a certificate from PEM encoded data.
+
+    :param bytes data: The PEM encoded certificate data.
+
+    :param backend: A backend supporting the
+        :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
+        interface.
+
+    :returns: An instance of
+        :class:`~cryptography.hazmat.primitives.interfaces.X509Certificate`.
+
+.. function:: load_der_x509_certificate(data, backend)
+
+    .. versionadded:: 0.7
+
+    Deserialize a certificate from DER encoded data.
+
+    :param bytes data: The DER encoded certificate data.
+
+    :param backend: A backend supporting the
+        :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
+        interface.
+
+    :returns: An instance of
+        :class:`~cryptography.hazmat.primitives.interfaces.X509Certificate`.
+
+.. testsetup::
+
+    pem_data = b"""
+    -----BEGIN CERTIFICATE-----
+    MIIDfDCCAmSgAwIBAgIBAjANBgkqhkiG9w0BAQsFADBFMQswCQYDVQQGEwJVUzEf
+    MB0GA1UEChMWVGVzdCBDZXJ0aWZpY2F0ZXMgMjAxMTEVMBMGA1UEAxMMVHJ1c3Qg
+    QW5jaG9yMB4XDTEwMDEwMTA4MzAwMFoXDTMwMTIzMTA4MzAwMFowQDELMAkGA1UE
+    BhMCVVMxHzAdBgNVBAoTFlRlc3QgQ2VydGlmaWNhdGVzIDIwMTExEDAOBgNVBAMT
+    B0dvb2QgQ0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCQWJpHYo37
+    Xfb7oJSPe+WvfTlzIG21WQ7MyMbGtK/m8mejCzR6c+f/pJhEH/OcDSMsXq8h5kXa
+    BGqWK+vSwD/Pzp5OYGptXmGPcthDtAwlrafkGOS4GqIJ8+k9XGKs+vQUXJKsOk47
+    RuzD6PZupq4s16xaLVqYbUC26UcY08GpnoLNHJZS/EmXw1ZZ3d4YZjNlpIpWFNHn
+    UGmdiGKXUPX/9H0fVjIAaQwjnGAbpgyCumWgzIwPpX+ElFOUr3z7BoVnFKhIXze+
+    VmQGSWxZxvWDUN90Ul0tLEpLgk3OVxUB4VUGuf15OJOpgo1xibINPmWt14Vda2N9
+    yrNKloJGZNqLAgMBAAGjfDB6MB8GA1UdIwQYMBaAFOR9X9FclYYILAWuvnW2ZafZ
+    XahmMB0GA1UdDgQWBBRYAYQkG7wrUpRKPaUQchRR9a86yTAOBgNVHQ8BAf8EBAMC
+    AQYwFwYDVR0gBBAwDjAMBgpghkgBZQMCATABMA8GA1UdEwEB/wQFMAMBAf8wDQYJ
+    KoZIhvcNAQELBQADggEBADWHlxbmdTXNwBL/llwhQqwnazK7CC2WsXBBqgNPWj7m
+    tvQ+aLG8/50Qc2Sun7o2VnwF9D18UUe8Gj3uPUYH+oSI1vDdyKcjmMbKRU4rk0eo
+    3UHNDXwqIVc9CQS9smyV+x1HCwL4TTrq+LXLKx/qVij0Yqk+UJfAtrg2jnYKXsCu
+    FMBQQnWCGrwa1g1TphRp/RmYHnMynYFmZrXtzFz+U9XEA7C+gPq4kqDI/iVfIT1s
+    6lBtdB50lrDVwl2oYfAvW/6sC2se2QleZidUmrziVNP4oEeXINokU6T6p//HM1FG
+    QYw2jOvpKcKtWCSAnegEbgsGYzATKjmPJPJ0npHFqzM=
+    -----END CERTIFICATE-----
+    """.strip()
+
+.. doctest::
+
+    >>> from cryptography.x509 import load_pem_x509_certificate
+    >>> from cryptography.hazmat.backends import default_backend
+    >>> cert = load_pem_x509_certificate(pem_data, default_backend())
+    >>> cert.serial
+    2
+
+Support Classes
+~~~~~~~~~~~~~~~
+
+.. class:: X509Version
+
+    .. versionadded:: 0.7
+
+    An enumeration for X.509 versions.
+
+    .. attribute:: v1
+
+        For version 1 X.509 certificates.
+
+    .. attribute:: v3
+
+        For version 3 X.509 certificates.
+
+
+
+.. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure
diff --git a/src/cryptography/hazmat/backends/openssl/x509.py b/src/cryptography/hazmat/backends/openssl/x509.py
index 9f12da0e..0c6395f4 100644
--- a/src/cryptography/hazmat/backends/openssl/x509.py
+++ b/src/cryptography/hazmat/backends/openssl/x509.py
@@ -15,8 +15,8 @@ from __future__ import absolute_import, division, print_function
 
 import datetime
 
-from cryptography import utils
-from cryptography.hazmat.primitives import hashes, interfaces, x509
+from cryptography import utils, x509
+from cryptography.hazmat.primitives import hashes, interfaces
 
 
 @utils.register_interface(interfaces.X509Certificate)
diff --git a/src/cryptography/hazmat/primitives/serialization.py b/src/cryptography/hazmat/primitives/serialization.py
index 077d56a5..0dbbc85c 100644
--- a/src/cryptography/hazmat/primitives/serialization.py
+++ b/src/cryptography/hazmat/primitives/serialization.py
@@ -116,7 +116,3 @@ else:
             data = data[4:]
 
         return result
-
-
-def load_pem_x509_certificate(data, backend):
-    return backend.load_pem_x509_certificate(data)
diff --git a/src/cryptography/x509.py b/src/cryptography/x509.py
new file mode 100644
index 00000000..b7220239
--- /dev/null
+++ b/src/cryptography/x509.py
@@ -0,0 +1,23 @@
+# This file is dual licensed under the terms of the Apache License, Version
+# 2.0, and the BSD License. See the LICENSE file in the root of this repository
+# for complete details.
+
+from __future__ import absolute_import, division, print_function
+
+from enum import Enum
+
+
+# TODO: document this
+class X509Version(Enum):
+    v1 = 0
+    v3 = 2
+
+
+# TODO: document this
+def load_pem_x509_certificate(data, backend):
+    return backend.load_pem_x509_certificate(data)
+
+
+# TODO: document this
+def load_der_x509_certificate(data, backend):
+    return backend.load_der_x509_certificate(data)
diff --git a/tests/test_x509.py b/tests/test_x509.py
new file mode 100644
index 00000000..97102946
--- /dev/null
+++ b/tests/test_x509.py
@@ -0,0 +1,85 @@
+# This file is dual licensed under the terms of the Apache License, Version
+# 2.0, and the BSD License. See the LICENSE file in the root of this repository
+# for complete details.
+
+from __future__ import absolute_import, division, print_function
+
+import base64
+import datetime
+import os
+import textwrap
+
+import pytest
+
+from cryptography import x509
+from cryptography.hazmat.backends.interfaces import RSABackend, X509Backend
+from cryptography.hazmat.primitives import interfaces
+
+from .hazmat.primitives.utils import load_vectors_from_file
+
+
+def _der_to_pem(data):
+    lines = textwrap.wrap(base64.b64encode(data), 64)
+    return (
+        "-----BEGIN CERTIFICATE-----\n" +
+        "\n".join(lines) +
+        "\n-----END CERTIFICATE-----"
+    )
+
+
+def _load_der_cert(name, backend):
+    cert = load_vectors_from_file(
+        os.path.join(
+            "x509", "PKITS_data", "certs", name),
+        lambda pemfile: x509.load_der_x509_certificate(
+            pemfile.read(), backend
+        )
+    )
+    return cert
+
+
+@pytest.mark.requires_backend_interface(interface=RSABackend)
+@pytest.mark.requires_backend_interface(interface=X509Backend)
+class TestX509Certificate(object):
+    def test_load_good_ca_cert(self, backend):
+        cert = _load_der_cert("GoodCACert.crt", backend)
+
+        assert cert
+        assert cert.not_before == datetime.datetime(2010, 1, 1, 8, 30)
+        assert cert.not_after == datetime.datetime(2030, 12, 31, 8, 30)
+        assert cert.serial == 2
+        public_key = cert.public_key()
+        assert isinstance(public_key, interfaces.RSAPublicKey)
+        assert cert.version == x509.X509Version.v3
+
+    def test_pre_2000_utc_not_before_cert(self, backend):
+        cert = _load_der_cert(
+            "Validpre2000UTCnotBeforeDateTest3EE.crt",
+            backend
+        )
+
+        assert cert
+        assert cert.not_before == datetime.datetime(1950, 1, 1, 12, 1)
+        assert cert.not_after == datetime.datetime(2030, 12, 31, 8, 30)
+        assert cert.version == x509.X509Version.v3
+
+    def test_generalized_time_not_before_cert(self, backend):
+        cert = _load_der_cert(
+            "ValidGeneralizedTimenotBeforeDateTest4EE.crt",
+            backend
+        )
+
+        assert cert
+        assert cert.not_before == datetime.datetime(2002, 1, 1, 12, 1)
+        assert cert.not_after == datetime.datetime(2030, 12, 31, 8, 30)
+        assert cert.version == x509.X509Version.v3
+
+    def test_generalized_time_not_after_cert(self, backend):
+        cert = _load_der_cert(
+            "ValidGeneralizedTimenotAfterDateTest8EE.crt",
+            backend
+        )
+        assert cert
+        assert cert.not_before == datetime.datetime(2010, 1, 1, 8, 30)
+        assert cert.not_after == datetime.datetime(2050, 1, 1, 12, 1)
+        assert cert.version == x509.X509Version.v3