4 files changed, 197 insertions, 0 deletions
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
new file mode 100644
index 00000000..f88b965a
--- /dev/null
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -0,0 +1,51 @@
+.. hazmat::
+
+Elliptic Curve
+==============
+
+.. currentmodule:: cryptography.hazmat.primitives.asymmetric.ec
+
+
+.. class:: EllipticCurvePrivateNumbers(private_value, public_numbers)
+
+    .. versionadded:: 0.5
+
+    The collection of integers that make up an EC private key.
+
+    .. attribute:: public_numbers
+
+        :type: :class:`~cryptography.hazmat.primitives.ec.EllipticCurvePublicNumbers`
+
+        The :class:`EllipticCurvePublicNumbers` which makes up the EC public
+        key associated with this EC private key.
+
+    .. attribute:: private_value
+
+        :type: int
+
+        The private value.
+
+
+.. class:: EllipticCurvePublicNumbers(x, y, curve)
+
+    .. versionadded:: 0.5
+
+    The collection of integers that make up an EC public key.
+
+     .. attribute:: curve
+
+        :type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve`
+
+        The elliptic curve for this key.
+
+    .. attribute:: x
+
+        :type: int
+
+        The affine x component of the public point used for verifying.
+
+    .. attribute:: y
+
+        :type: int
+
+        The affine y component of the public point used for verifying.
diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst
index 047f9cb9..6a5228ba 100644
--- a/docs/hazmat/primitives/asymmetric/index.rst
+++ b/docs/hazmat/primitives/asymmetric/index.rst
@@ -7,6 +7,7 @@ Asymmetric algorithms
     :maxdepth: 1
 
     dsa
+    ec
     rsa
     padding
     serialization
diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index 8d32ae58..2b3eb511 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -9,6 +9,58 @@ There are several common schemes for serializing asymmetric private and public
 keys to bytes. They generally support encryption of private keys and additional
 key metadata.
 
+Many serialization formats support multiple different types of asymmetric keys
+and will return an an instance of the appropriate type. You should check that
+the returned key matches the type your application expects when using these
+methods.
+
+    .. code-block:: pycon
+
+        >>> key = load_pkcs8_private_key(pem_data, None, backend)
+        >>> if isinstance(key, rsa.RSAPrivateKey):
+        >>>     signature = sign_with_rsa_key(key, message)
+        >>> elif isinstance(key, dsa.DSAPrivateKey):
+        >>>     signature = sign_with_dsa_key(key, message)
+        >>> else:
+        >>>     raise TypeError
+
+
+PKCS #8 Format
+~~~~~~~~~~~~~~
+
+PKCS #8 is a serialization format originally standardized by RSA and
+currently maintained by the IETF in :rfc:`5208`. It supports password based
+encryption and additional key metadata attributes.
+
+
+.. function:: load_pkcs8_private_key(data, password, backend)
+
+    .. versionadded:: 0.5
+
+    Deserialize a private key from PEM encoded data to one of the supported
+    asymmetric private key types.
+
+    :param bytes data: The PEM encoded key data.
+
+    :param bytes password: The password to use to decrypt the data. Should
+        be ``None`` if the private key is not encrypted.
+    :param backend: A
+        :class:`~cryptography.hazmat.backends.interfaces.PKCS8SerializationBackend`
+        provider.
+
+    :returns: A new instance of a private key.
+
+    :raises ValueError: If the PEM data could not be decrypted or if its
+        structure could not be decoded successfully.
+
+    :raises TypeError: If a ``password`` was given and the private key was
+        not encrypted. Or if the key was encrypted but no
+        password was supplied.
+
+    :raises UnsupportedAlgorithm: If the serialized key is of a type that
+        is not supported by the backend or if the key is encrypted with a
+        symmetric cipher that is not supported by the backend.
+
 
 Traditional OpenSSL Format
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index dc09a26f..b2857f58 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -463,6 +463,97 @@ Asymmetric interfaces
             :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext`
 
 
+.. class:: EllipticCurve
+
+    .. versionadded:: 0.5
+
+    A named elliptic curve.
+
+    .. attribute:: name
+
+        :type: string
+
+        The name of the curve. Usually the name used for the ASN.1 OID such as
+        ``secp256k1``.
+
+    .. attribute:: key_size
+
+        :type: int
+
+        The bit length of the curve's base point.
+
+
+.. class:: EllipticCurveSignatureAlgorithm
+
+    .. versionadded:: 0.5
+
+    A signature algorithm for use with elliptic curve keys.
+
+    .. attribute:: algorithm
+
+        :type: :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+
+        The digest algorithm to be used with the signature scheme.
+
+
+.. class:: EllipticCurvePrivateKey
+
+    .. versionadded:: 0.5
+
+    An elliptic curve private key for use with an algorithm such as `ECDSA`_ or
+    `EdDSA`_.
+
+    .. classmethod:: signer(signature_algorithm)
+
+        Sign data which can be verified later by others using the public key.
+
+        :param signature_algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurveSignatureAlgorithm`
+            provider.
+
+        :returns:
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
+
+    .. attribute:: curve
+
+        :type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve`
+
+        The elliptic curve for this key.
+
+    .. method:: public_key()
+
+        :return: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicKey`
+
+        The EllipticCurvePublicKey object for this private key.
+
+
+.. class:: EllipticCurvePublicKey
+
+    .. versionadded:: 0.5
+
+    An elliptic curve public key.
+
+    .. classmethod:: verifier(signer, signature_algorithm)
+
+        Verify data was signed by the private key associated with this public
+        key.
+
+        :param bytes signature: The signature to verify.
+
+        :param signature_algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurveSignatureAlgorithm`
+            provider.
+
+        :returns:
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
+
+     .. attribute:: curve
+
+        :type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve`
+
+        The elliptic curve for this key.
+
+
 .. class:: AsymmetricSignatureContext
 
     .. versionadded:: 0.2
@@ -612,3 +703,5 @@ Key derivation functions
 .. _`Chinese remainder theorem`: https://en.wikipedia.org/wiki/Chinese_remainder_theorem
 .. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm
 .. _`CMAC`: https://en.wikipedia.org/wiki/CMAC
+.. _`ECDSA`: http://en.wikipedia.org/wiki/ECDSA
+.. _`EdDSA`: http://en.wikipedia.org/wiki/EdDSA