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@xxxxxxx> Cc: "Gustavo A. R. Silva" <gustavoars@xxxxxxxxxx> Cc: Justin Stitt <justinstitt@xxxxxxxxxx> Cc: workflows@xxxxxxxxxxxxxxx Cc: linux-doc@xxxxxxxxxxxxxxx Signed-off-by: Kees Cook <keescook@xxxxxxxxxxxx> --- 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
