move x509 to top level, add more docs
diff --git a/docs/index.rst b/docs/index.rst
index 083533c..918b43a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -67,6 +67,7 @@
exceptions
faq
glossary
+ x509
The hazardous materials layer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/x509.rst b/docs/x509.rst
new file mode 100644
index 0000000..5d18297
--- /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