add ec.private_key_from_secret_and_curve (#3225)

* finish https://github.com/pyca/cryptography/pull/1973

* change API & add test

Function will now return an instance of EllipticCurvePrivateKey, as that
is the users' ultimate goal anyway.

* fix test

* improve coverage

* complete coverage

* final fix

* centos fix

* retry

* cleanup asserts

* use openssl_assert

* skip unsupported platforms

* change API name to derive_private_key

* change version added

* improve description of `secret` param

* separate successful and failure test cases

* simplify successful case

* add docs for derive_elliptic_curve_public_point

* add period

2 files changed, 25 insertions, 0 deletions

diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index b79bb239..0a0d1456 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -422,6 +422,15 @@ A specific ``backend`` may provide one or more of these interfaces.
         :returns: An instance of
             :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`.
 
+    .. method:: derive_elliptic_curve_public_point(private_value, curve)
+
+        :param private_value: A secret scalar value.
+
+        :param curve: An instance of
+            :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve`.
+
+        :returns: A tuple (x, y).
+
 .. class:: PEMSerializationBackend
 
     .. versionadded:: 0.6
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 2421d921..33ebee0f 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -20,6 +20,22 @@ Elliptic curve cryptography
     :returns: A new instance of :class:`EllipticCurvePrivateKey`.
 
 
+.. function:: derive_private_key(secret, curve, backend)
+
+    .. versionadded:: 1.6
+
+    Derive a private key from ``secret`` on ``curve`` for use with ``backend``.
+
+    :param int secret: The secret scalar value.
+
+    :param curve: An instance of :class:`EllipticCurve`.
+
+    :param backend: An instance of
+        :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`.
+
+    :returns: A new instance of :class:`EllipticCurvePrivateKey`.
+
+
 Elliptic Curve Signature Algorithms
 -----------------------------------