diff --git a/Documentation/guides/fortify.rst b/Documentation/guides/fortify.rst new file mode 100644 index 00000000000..baa325d16ee --- /dev/null +++ b/Documentation/guides/fortify.rst @@ -0,0 +1,77 @@ +======== +Fortify +======== + +Overview +-------- + +A common error in C programs is invoking functions that might exceed memory bounds, +causing crashes or undefined behavior. Examples include incorrect usage of functions like +``memcpy`` and ``memset``. `FORTIFY_SOURCE` is a mechanism designed to help developers quickly +detect and mitigate boundary-related issues caused by improper use of library functions. + +Support +------- + +`FORTIFY_SOURCE` is implemented as a software check by the compiler and is supported across all architectures. +It works by adding additional validation checks to standard library function calls. + +Usage +----- + +To enable `FORTIFY_SOURCE`, configure the kernel with the following option: + +``CONFIG_FORTIFY_SOURCE=level`` + +Where `level` can be set as: + +1. **Compile-time Checks**: + Detects issues during compilation by analyzing source code. + +2. **Stack Variable Checks**: + Extends level 1 by checking stack variables at runtime. + +3. **Heap Memory Checks**: + Builds on level 2 by adding checks for memory allocated with ``malloc``. + (Requires GCC version 12 or later.) + +FORTIFY_SOURCE Overview +======================= + +`FORTIFY_SOURCE` detects potential security vulnerabilities by statically analyzing source code at compile time. +It replaces standard library function calls with safer versions that include additional boundary checks. +These safer versions validate the operation's boundaries and the input's validity before performing certain operations. + +GCC Built-in Functions +----------------------- + +The GCC compiler internally implements two key functions for `FORTIFY_SOURCE`: + +- ``__builtin_object_size``: Determines the size of a statically allocated object. +- ``__builtin_dynamic_object_size``: Determines the size of dynamically allocated objects (e.g., via ``malloc``). + +Starting with GCC 12, these functions support retrieving the size of variables allocated with ``malloc``. + +By passing a variable or buffer as an argument to these functions, the compiler can compute the corresponding size. +Using this size, it is possible to check for potential out-of-bounds behavior in runtime operations. + +Example: memcpy Implementation in NuttX +---------------------------------------- + +The following example demonstrates how `FORTIFY_SOURCE` can be used to enhance security in a ``memcpy`` +implementation in NuttX: + +.. code-block:: c + + fortify_function(memcpy) + FAR void *memcpy(FAR void *dest, + FAR const void *src, + size_t n) + { + fortify_assert(n <= fortify_size(dest, 0) && n <= fortify_size(src, 0)); + return __real_memcpy(dest, src, n); + } + +In this implementation, the ``fortify_assert`` macro ensures that the size of the source and destination buffers +is sufficient to handle the requested memory operation. If the assertion fails, it indicates a potential buffer +overflow, helping developers quickly identify and address such vulnerabilities. diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst index e7b3b494b9d..4093e2c1fbf 100644 --- a/Documentation/guides/index.rst +++ b/Documentation/guides/index.rst @@ -20,6 +20,7 @@ Guides citests.rst zerolatencyinterrupts.rst kasan.rst + fortify.rst nestedinterrupts.rst cortexmhardfaults.rst coredump.rst