bpo-37977: Warn more strongly and clearly about pickle security (GH-15595)

Author: lordmauve

Doc/library/pickle.rst

@@ -30,9 +30,17 @@ avoid confusion, the terms used here are "pickling" and "unpickling".
 
 .. warning::
 
-   The :mod:`pickle` module is not secure against erroneous or maliciously
-   constructed data.  Never unpickle data received from an untrusted or
-   unauthenticated source.
+   The ``pickle`` module **is not secure**. Only unpickle data you trust.
+
+   It is possible to construct malicious pickle data which will **execute
+   arbitrary code during unpickling**. Never unpickle data that could have come
+   from an untrusted source, or that could have been tampered with.
+
+   Consider signing data with :mod:`hmac` if you need to ensure that it has not
+   been tampered with.
+
+   Safer serialization formats such as :mod:`json` may be more appropriate if
+   you are processing untrusted data. See :ref:`comparison-with-json`.
 
 
 Relationship to other Python modules
@@ -75,6 +83,9 @@ The :mod:`pickle` module differs from :mod:`marshal` in several significant ways
   pickling and unpickling code deals with Python 2 to Python 3 type differences
   if your data is crossing that unique breaking change language boundary.
 
+
+.. _comparison-with-json:
+
 Comparison with ``json``
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -94,7 +105,10 @@ There are fundamental differences between the pickle protocols and
   types, and no custom classes; pickle can represent an extremely large
   number of Python types (many of them automatically, by clever usage
   of Python's introspection facilities; complex cases can be tackled by
-  implementing :ref:`specific object APIs <pickle-inst>`).
+  implementing :ref:`specific object APIs <pickle-inst>`);
+
+* Unlike pickle, deserializing untrusted JSON does not in itself create an
+  arbitrary code execution vulnerability.
 
 .. seealso::
    The :mod:`json` module: a standard library module allowing JSON

Misc/NEWS.d/next/Documentation/2019-08-29-14-38-01.bpo-37977.pML-UI.rst

@@ -0,0 +1 @@
+Warn more strongly and clearly about pickle insecurity