- Issue #13703: oCERT-2011-003: add -R command-line option and PYTHONHASHSEED
environment variable, to provide an opt-in way to protect against denial of
service attacks due to hash collisions within the dict and set types. Patch
by David Malcolm, based on work by Victor Stinner.
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index b41d244..38d724f 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -21,7 +21,7 @@
When invoking Python, you may specify any of these options::
- python [-BdEiOQsStuUvVWxX3?] [-c command | -m module-name | script | - ] [args]
+ python [-BdEiOQsRStuUvVWxX3?] [-c command | -m module-name | script | - ] [args]
The most common use case is, of course, a simple invocation of a script::
@@ -239,6 +239,29 @@
:pep:`238` -- Changing the division operator
+.. cmdoption:: -R
+
+ Turn on hash randomization, so that the :meth:`__hash__` values of str,
+ bytes and datetime objects are "salted" with an unpredictable random value.
+ Although they remain constant within an individual Python process, they are
+ not predictable between repeated invocations of Python.
+
+ This is intended to provide protection against a denial-of-service caused by
+ carefully-chosen inputs that exploit the worst case performance of a dict
+ insertion, O(n^2) complexity. See
+ http://www.ocert.org/advisories/ocert-2011-003.html for details.
+
+ Changing hash values affects the order in which keys are retrieved from a
+ dict. Although Python has never made guarantees about this ordering (and it
+ typically varies between 32-bit and 64-bit builds), enough real-world code
+ implicitly relies on this non-guaranteed behavior that the randomization is
+ disabled by default.
+
+ See also :envvar:`PYTHONHASHSEED`.
+
+ .. versionadded:: 2.6.8
+
+
.. cmdoption:: -s
Don't add user site directory to sys.path
@@ -501,6 +524,27 @@
.. versionadded:: 2.6
+.. envvar:: PYTHONHASHSEED
+
+ If this variable is set to ``random``, the effect is the same as specifying
+ the :option:`-R` option: a random value is used to seed the hashes of str,
+ bytes and datetime objects.
+
+ If :envvar:`PYTHONHASHSEED` is set to an integer value, it is used as a
+ fixed seed for generating the hash() of the types covered by the hash
+ randomization.
+
+ Its purpose is to allow repeatable hashing, such as for selftests for the
+ interpreter itself, or to allow a cluster of python processes to share hash
+ values.
+
+ The integer must be a decimal number in the range [0,4294967295].
+ Specifying the value 0 will lead to the same hash values as when hash
+ randomization is disabled.
+
+ .. versionadded:: 2.6.8
+
+
.. envvar:: PYTHONIOENCODING
Overrides the encoding used for stdin/stdout/stderr, in the syntax