Break users on OpenSSL 1.0.2 (#5438)

fixes #5432

2 files changed, 15 insertions, 1 deletions

diff --git a/docs/faq.rst b/docs/faq.rst
index dba7b05ed..33c5417d1 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -109,6 +109,19 @@ Your ``pip`` and/or ``setuptools`` are outdated. Please upgrade to the latest
 versions with ``pip install -U pip setuptools`` (or on Windows
 ``python -m pip install -U pip setuptools``).
 
+Importing cryptography causes a ``RuntimeError`` about OpenSSL 1.0.2
+--------------------------------------------------------------------
+
+The OpenSSL project has dropped support for the 1.0.2 release series. Since it
+is no longer receiving security patches from upstream, ``cryptography`` is also
+dropping support for it. To fix this issue you should upgrade to a newer
+version of OpenSSL (1.1.0 or later). This may require you to upgrade to a newer
+operating system.
+
+For the 3.2 release, you can set the ``CRYPTOGRAPHY_ALLOW_OPENSSL_102``
+environment variable. Please note that this is *temporary* and will be removed
+in ``cryptography`` 3.3.
+
 Installing cryptography with OpenSSL 0.9.8, 1.0.0, 1.0.1 fails
 --------------------------------------------------------------
 
diff --git a/docs/installation.rst b/docs/installation.rst
index 62126fc76..c773fdce5 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -33,7 +33,8 @@ OpenSSL releases:
 
 .. warning::
 
-    Cryptography 3.1 has deprecated support for OpenSSL 1.0.2.
+    Cryptography 3.2 has dropped support for OpenSSL 1.0.2, see the
+    :doc:`FAQ </faq>` for more details
 
 Building cryptography on Windows
 --------------------------------