diff options
| author | Daniel Pope <lordmauve@users.noreply.github.com> | 2019-08-31 05:51:33 (GMT) |
|---|---|---|
| committer | Raymond Hettinger <rhettinger@users.noreply.github.com> | 2019-08-31 05:51:33 (GMT) |
| commit | daa82d019c52e95c3c57275307918078c1c0ac81 (patch) | |
| tree | b3b8bd652552eca4973b58cfaa94986dbb36143a /Doc/library/pickle.rst | |
| parent | 013e52fd340d9ef558013b546f25456f94ee1804 (diff) | |
| download | cpython-daa82d019c52e95c3c57275307918078c1c0ac81.zip cpython-daa82d019c52e95c3c57275307918078c1c0ac81.tar.gz cpython-daa82d019c52e95c3c57275307918078c1c0ac81.tar.bz2 | |
bpo-37977: Warn more strongly and clearly about pickle security (GH-15595)
Diffstat (limited to 'Doc/library/pickle.rst')
| -rw-r--r-- | Doc/library/pickle.rst | 22 |
1 files changed, 18 insertions, 4 deletions
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index 09c9c86..eb58178 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 |