better document hte iface

2 files changed, 26 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 9b2e61fb..525bd6cb 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -132,6 +132,9 @@ Elliptic Curve Key Exchange algorithm
     The Elliptic Curve Diffie-Hellman Key Exchange algorithm first standardized
     in NIST publication `800-56A`_, and later in `800-56Ar2`_.
 
+    For most applications the ``shared_key`` should be passed to a key
+    derivation function.
+
     .. doctest::
 
         >>> from cryptography.hazmat.backends import default_backend
@@ -337,6 +340,22 @@ Key Interfaces
         :returns:
             :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext`
 
+    .. method:: exchange(algorithm, peer_public_key)
+
+        Perform's a key exchange operation using the provided algorithm with
+        the peer's public key.
+
+        For most applications the result should be passed to a key derivation
+        function.
+
+        :param algorithm: The key exchange algorithm, currently only
+            :class:`~cryptography.hazmat.primitives.asymmetric.ec.ECDH` is
+            supported.
+        :param EllipticCurvePublicKey peer_public_key: The public key for the
+            peer.
+
+        :returns bytes: A shared key.
+
     .. method:: public_key()
 
         :return: :class:`EllipticCurvePublicKey`
diff --git a/src/cryptography/hazmat/primitives/asymmetric/ec.py b/src/cryptography/hazmat/primitives/asymmetric/ec.py
index 052ae742..c6f83667 100644
--- a/src/cryptography/hazmat/primitives/asymmetric/ec.py
+++ b/src/cryptography/hazmat/primitives/asymmetric/ec.py
@@ -44,6 +44,13 @@ class EllipticCurvePrivateKey(object):
         """
 
     @abc.abstractmethod
+    def exchange(self, algorithm, peer_public_key):
+        """
+        Performs a key exchange operation using the provided algorithm with the
+        provided peer's public key.
+        """
+
+    @abc.abstractmethod
     def public_key(self):
         """
         The EllipticCurvePublicKey for this private key.