add note about cryptography to crypto module (#666)
fixes #663
diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst
index e7190ab..04d7ccf 100644
--- a/doc/api/crypto.rst
+++ b/doc/api/crypto.rst
@@ -6,6 +6,15 @@
.. py:module:: OpenSSL.crypto
:synopsis: Generic cryptographic module
+.. note::
+
+ `pyca/cryptography`_ is likely a better choice than using this module. It
+ contains a complete set of cryptographic primitives as well as a
+ significantly better and more powerful X509 API. If necessary you can
+ convert to and from cryptography objects using the ``to_cryptography``
+ and ``from_cryptography`` methods on ``X509``, ``X509Req``, ``CRL``,
+ and ``PKey``.
+
Elliptic curves
---------------
@@ -321,3 +330,4 @@
This page can be found online for the latest version of OpenSSL:
https://www.openssl.org/docs/manmaster/man3/EVP_DigestInit.html
+.. _`pyca/cryptography`: https://cryptography.io