Doc: Fortify Instructions

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.

Documentation/guides/index.rst

@@ -20,6 +20,7 @@ Guides
   citests.rst
   zerolatencyinterrupts.rst
   kasan.rst
+  fortify.rst
   nestedinterrupts.rst
   cortexmhardfaults.rst
   coredump.rst