[PATCH 04/82] docs: deprecated.rst: deprecate open-coded arithmetic wrap-around
From: Kees Cook <hidden>
Date: 2024-01-23 00:28:34
Also in:
linux-hardening, lkml, workflows
Subsystem:
documentation, documentation process, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
In pursuit of gaining full kernel instrumentation for signed[1], unsigned[2], and pointer[3] arithmetic overflow, we need to replace the handful of instances in the kernel where we intentionally depend on arithmetic wrap-around. Document this goal and provide an example for the most common code pattern, checking for simple overflow: if (VAR + OFFSET < VAR) ... Link: https://github.com/KSPP/linux/issues/26 [1] Link: https://github.com/KSPP/linux/issues/27 [2] Link: https://github.com/KSPP/linux/issues/344 [3] Cc: Jonathan Corbet <corbet@lwn.net> Cc: "Gustavo A. R. Silva" <gustavoars@kernel.org> Cc: Justin Stitt <justinstitt@google.com> Cc: workflows@vger.kernel.org Cc: linux-doc@vger.kernel.org Signed-off-by: Kees Cook <redacted> --- Documentation/process/deprecated.rst | 32 ++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+)
diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index 1f7f3e6c9cda..270f3af13b86 100644
--- a/Documentation/process/deprecated.rst
+++ b/Documentation/process/deprecated.rst@@ -109,6 +109,38 @@ For more details, also see array3_size() and flex_array_size(), as well as the related check_mul_overflow(), check_add_overflow(), check_sub_overflow(), and check_shl_overflow() family of functions. +open-coded intentional arithmetic wrap-around +--------------------------------------------- +Depending on arithmetic wrap-around without annotations means the +kernel cannot distinguish between intentional wrap-around and accidental +wrap-around (when using things like the overflow sanitizers). + +For example, where an addition is intended to wrap around:: + + magic = counter + rotation; + +please use the add_wrap() helper:: + + magic = add_wrap(counter, rotation); + +Another common code pattern in the kernel open coded testing for overflow +by performing an overflow and looking for wrap-around:: + + if (var + offset < var) ... + +Instead, use either check_add_overflow() (when you want to use the +resulting sum when it doesn't overflow) or add_would_overflow():: + + if (add_would_overflow(var, offset)) ... + +In rare cases where helpers aren't available (e.g. in early boot code, +etc) but overflow instrumentation still needs to be avoided, it can be +replaced with a type max subtraction test instead:: + + int var; + ... + if (INT_MAX - var < offset) ... + simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() ---------------------------------------------------------------------- The simple_strtol(), simple_strtoll(),
--
2.34.1