@@ -5244,6 +5244,165 @@ types, where they are relevant. Some of these are not reported by the
52445244 [<class 'bool'>]
52455245
52465246
5247+ .. _int_max_str_digits :
5248+
5249+ Integer string conversion length limitation
5250+ ===========================================
5251+
5252+ CPython has a global limit for converting between :class: `int ` and :class: `str `
5253+ to mitigate denial of service attacks. This limit *only * applies to decimal or
5254+ other non-power-of-two number bases. Hexadecimal, octal, and binary conversions
5255+ are unlimited. The limit can be configured.
5256+
5257+ The :class: `int ` type in CPython is an abitrary length number stored in binary
5258+ form (commonly known as a "bignum"). There exists no algorithm that can convert
5259+ a string to a binary integer or a binary integer to a string in linear time,
5260+ *unless * the base is a power of 2. Even the best known algorithms for base 10
5261+ have sub-quadratic complexity. Converting a large value such as ``int('1' *
5262+ 500_000) `` can take over a second on a fast CPU.
5263+
5264+ Limiting conversion size offers a practical way to avoid `CVE-2020-10735
5265+ <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735> `_.
5266+
5267+ The limit is applied to the number of digit characters in the input or output
5268+ string when a non-linear conversion algorithm would be involved. Underscores
5269+ and the sign are not counted towards the limit.
5270+
5271+ When an operation would exceed the limit, a :exc: `ValueError ` is raised:
5272+
5273+ .. doctest ::
5274+
5275+ >>> import sys
5276+ >>> sys.set_int_max_str_digits(4300 ) # Illustrative, this is the default.
5277+ >>> _ = int (' 2' * 5432 )
5278+ Traceback (most recent call last):
5279+ ...
5280+ ValueError: Exceeds the limit (4300) for integer string conversion: value has 5432 digits.
5281+ >>> i = int (' 2' * 4300 )
5282+ >>> len (str (i))
5283+ 4300
5284+ >>> i_squared = i* i
5285+ >>> len (str (i_squared))
5286+ Traceback (most recent call last):
5287+ ...
5288+ ValueError: Exceeds the limit (4300) for integer string conversion: value has 8599 digits.
5289+ >>> len (hex (i_squared))
5290+ 7144
5291+ >>> assert int (hex (i_squared), base = 16 ) == i* i # Hexadecimal is unlimited.
5292+
5293+ The default limit is 4300 digits as provided in
5294+ :data: `sys.int_info.default_max_str_digits <sys.int_info> `.
5295+ The lowest limit that can be configured is 640 digits as provided in
5296+ :data: `sys.int_info.str_digits_check_threshold <sys.int_info> `.
5297+
5298+ Verification:
5299+
5300+ .. doctest ::
5301+
5302+ >>> import sys
5303+ >>> assert sys.int_info.default_max_str_digits == 4300 , sys.int_info
5304+ >>> assert sys.int_info.str_digits_check_threshold == 640 , sys.int_info
5305+ >>> msg = int (' 578966293710682886880994035146873798396722250538762761564'
5306+ ... ' 9252925514383915483333812743580549779436104706260696366600'
5307+ ... ' 571186405732' 53 , ' big'
5308+ ...
5309+
5310+ .. versionadded :: 3.9.14
5311+
5312+ Affected APIs
5313+ -------------
5314+
5315+ The limitation only applies to potentially slow conversions between :class: `int `
5316+ and :class: `str ` or :class: `bytes `:
5317+
5318+ * ``int(string) `` with default base 10.
5319+ * ``int(string, base) `` for all bases that are not a power of 2.
5320+ * ``str(integer) ``.
5321+ * ``repr(integer) ``
5322+ * any other string conversion to base 10, for example ``f"{integer}" ``,
5323+ ``"{}".format(integer) ``, or ``b"%d" % integer ``.
5324+
5325+ The limitations do not apply to functions with a linear algorithm:
5326+
5327+ * ``int(string, base) `` with base 2, 4, 8, 16, or 32.
5328+ * :func: `int.from_bytes ` and :func: `int.to_bytes `.
5329+ * :func: `hex `, :func: `oct `, :func: `bin `.
5330+ * :ref: `formatspec ` for hex, octal, and binary numbers.
5331+ * :class: `str ` to :class: `float `.
5332+ * :class: `str ` to :class: `decimal.Decimal `.
5333+
5334+ Configuring the limit
5335+ ---------------------
5336+
5337+ Before Python starts up you can use an environment variable or an interpreter
5338+ command line flag to configure the limit:
5339+
5340+ * :envvar: `PYTHONINTMAXSTRDIGITS `, e.g.
5341+ ``PYTHONINTMAXSTRDIGITS=640 python3 `` to set the limit to 640 or
5342+ ``PYTHONINTMAXSTRDIGITS=0 python3 `` to disable the limitation.
5343+ * :option: `-X int_max_str_digits <-X> `, e.g.
5344+ ``python3 -X int_max_str_digits=640 ``
5345+ * :data: `sys.flags.int_max_str_digits ` contains the value of
5346+ :envvar: `PYTHONINTMAXSTRDIGITS ` or :option: `-X int_max_str_digits <-X> `.
5347+ If both the env var and the ``-X `` option are set, the ``-X `` option takes
5348+ precedence. A value of *-1 * indicates that both were unset, thus a value of
5349+ :data: `sys.int_info.default_max_str_digits ` was used during initilization.
5350+
5351+ From code, you can inspect the current limit and set a new one using these
5352+ :mod: `sys ` APIs:
5353+
5354+ * :func: `sys.get_int_max_str_digits ` and :func: `sys.set_int_max_str_digits ` are
5355+ a getter and setter for the interpreter-wide limit. Subinterpreters have
5356+ their own limit.
5357+
5358+ Information about the default and minimum can be found in :attr: `sys.int_info `:
5359+
5360+ * :data: `sys.int_info.default_max_str_digits <sys.int_info> ` is the compiled-in
5361+ default limit.
5362+ * :data: `sys.int_info.str_digits_check_threshold <sys.int_info> ` is the lowest
5363+ accepted value for the limit (other than 0 which disables it).
5364+
5365+ .. versionadded :: 3.9.14
5366+
5367+ .. caution ::
5368+
5369+ Setting a low limit *can * lead to problems. While rare, code exists that
5370+ contains integer constants in decimal in their source that exceed the
5371+ minimum threshold. A consequence of setting the limit is that Python source
5372+ code containing decimal integer literals longer than the limit will
5373+ encounter an error during parsing, usually at startup time or import time or
5374+ even at installation time - anytime an up to date ``.pyc `` does not already
5375+ exist for the code. A workaround for source that contains such large
5376+ constants is to convert them to ``0x `` hexadecimal form as it has no limit.
5377+
5378+ Test your application thoroughly if you use a low limit. Ensure your tests
5379+ run with the limit set early via the environment or flag so that it applies
5380+ during startup and even during any installation step that may invoke Python
5381+ to precompile ``.py `` sources to ``.pyc `` files.
5382+
5383+ Recommended configuration
5384+ -------------------------
5385+
5386+ The default :data: `sys.int_info.default_max_str_digits ` is expected to be
5387+ reasonable for most applications. If your application requires a different
5388+ limit, set it from your main entry point using Python version agnostic code as
5389+ these APIs were added in security patch releases in versions before 3.11.
5390+
5391+ Example::
5392+
5393+ >>> import sys
5394+ >>> if hasattr(sys, "set_int_max_str_digits"):
5395+ ... upper_bound = 68000
5396+ ... lower_bound = 4004
5397+ ... current_limit = sys.get_int_max_str_digits()
5398+ ... if current_limit == 0 or current_limit > upper_bound:
5399+ ... sys.set_int_max_str_digits(upper_bound)
5400+ ... elif current_limit < lower_bound:
5401+ ... sys.set_int_max_str_digits(lower_bound)
5402+
5403+ If you need to disable it entirely, set it to ``0 ``.
5404+
5405+
52475406.. rubric :: Footnotes
52485407
52495408.. [1 ] Additional information on these special methods may be found in the Python
0 commit comments