https://github.com/python/cpython/commit/6922b9e4fce635339cb94c2fdef6bba4e2a... commit: 6922b9e4fce635339cb94c2fdef6bba4e2a99621 branch: 3.8 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: Raymond Hettinger <rhettinger@users.noreply.github.com> date: 2019-08-30T23:02:15-07:00 summary: bpo-37977: Warn more strongly and clearly about pickle security (GH-15595) (GH-15629) (cherry picked from commit daa82d019c52e95c3c57275307918078c1c0ac81) Co-authored-by: Daniel Pope <lordmauve@users.noreply.github.com> files: A Misc/NEWS.d/next/Documentation/2019-08-29-14-38-01.bpo-37977.pML-UI.rst M Doc/library/pickle.rst diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index e6025aeaf476..9442efa2b667 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 diff --git a/Misc/NEWS.d/next/Documentation/2019-08-29-14-38-01.bpo-37977.pML-UI.rst b/Misc/NEWS.d/next/Documentation/2019-08-29-14-38-01.bpo-37977.pML-UI.rst new file mode 100644 index 000000000000..cd0fa3c0584a --- /dev/null +++ b/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