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

1 files changed, 18 insertions, 4 deletions

diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index 09c9c86abb..eb58178e0e 100644
--- a/Doc/library/pickle.rst
+++ b/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