move x509 to top level, add more docs

2 files changed, 98 insertions, 0 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