add some words about separating ECDH and ECDSA (#5423)

* add some words about separating ECDH and ECDSA

* Thomas Pornin wrote some good words about why you should try not to mix
your ECDH and ECDSA keys.

1 files changed, 9 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 4232e31df..72768f833 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -47,6 +47,10 @@ Elliptic Curve Signature Algorithms
     The ECDSA signature algorithm first standardized in NIST publication
     `FIPS 186-3`_, and later in `FIPS 186-4`_.
 
+    Note that while elliptic curve keys can be used for both signing and key
+    exchange, this is `bad cryptographic practice`_. Instead, users should
+    generate separate signing and ECDH keys.
+
     :param algorithm: An instance of
         :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
 
@@ -254,6 +258,10 @@ Elliptic Curve Key Exchange algorithm
     key, derivation of multiple keys, and destroys any structure that may be
     present.
 
+    Note that while elliptic curve keys can be used for both signing and key
+    exchange, this is `bad cryptographic practice`_. Instead, users should
+    generate separate signing and ECDH keys.
+
     .. warning::
 
         This example does not give `forward secrecy`_ and is only provided as a
@@ -972,3 +980,4 @@ Elliptic Curve Object Identifiers
 .. _`EdDSA`: https://en.wikipedia.org/wiki/EdDSA
 .. _`forward secrecy`: https://en.wikipedia.org/wiki/Forward_secrecy
 .. _`SEC 1 v2.0`: https://www.secg.org/sec1-v2.pdf
+.. _`bad cryptographic practice`: https://crypto.stackexchange.com/a/3313