Re: [PATCH v3] Add _FORTIFY_SOURCE implementation documentation [BZ #28998]

[Yann Droneaud <ydroneaud@opteya.com>]

Le 22/12/2022 à 17:04, Siddhesh Poyarekar via Libc-alpha a écrit :
> There have been multiple requests to provide more detail on how the
> _FORTIFY_SOURCE macro works, so this patch adds a new node in the
> Library Maintenance section that does this.  A lot of the description is
> implementation detail, which is why I put this in the appendix and not
> in the main documentation.
>
> Resolves: BZ #28998.
> Signed-off-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
> ---
> Changes from v2:
> - More massaging of the summary.
>
> Changes from v1:
> - Adjust wording to cover the non-buffer-overflow validation
> - Update function list
> - remove redundant 'See'
>
>   manual/creature.texi |   2 +
>   manual/maint.texi    | 222 +++++++++++++++++++++++++++++++++++++++++++
>   2 files changed, 224 insertions(+)
>
> diff --git a/manual/creature.texi b/manual/creature.texi
> index 530a02398e..47d1fc4607 100644
> --- a/manual/creature.texi
> +++ b/manual/creature.texi
> @@ -306,6 +306,8 @@ If this macro is defined to @math{1}, security hardening is added to
>   various library functions.  If defined to @math{2}, even stricter
>   checks are applied. If defined to @math{3}, @theglibc{} may also use
>   checks that may have an additional performance overhead.
> +@xref{Source Fortification,,Fortification of function calls} for more
> +information.
>   @end defvr
>   
>   @defvr Macro _DYNAMIC_STACK_SIZE_SOURCE
> diff --git a/manual/maint.texi b/manual/maint.texi
> index 49510db7bf..d9507f8ec3 100644
> --- a/manual/maint.texi
> +++ b/manual/maint.texi
> @@ -5,6 +5,7 @@
>   @menu
>   * Source Layout::         How to add new functions or header files
>                                to the GNU C Library.
> +* Source Fortification::  Fortification of function calls.
>   * Symbol handling::       How to handle symbols in the GNU C Library.
>   * Porting::               How to port the GNU C Library to
>                                a new machine or operating system.
> @@ -184,6 +185,227 @@ header file in the machine-specific directory, e.g.,
>   @file{sysdeps/powerpc/sys/platform/ppc.h}.
>   
>   
> +@node Source Fortification
> +@appendixsec Fortification of function calls
> +
> +This section contains implementation details of @theglibc{} and may not
> +remain stable across releases.
> +
> +The @code{_FORTIFY_SOURCE} macro may be defined by users to control
> +hardening of calls into some functions in @theglibc{}.

Macro must be defined before header inclusion.

>   The hardening
> +primarily focuses on accesses to buffers passed to the functions but may
> +also include checks for validity of other inputs to the functions.
> +
> +When the @code{_FORTIFY_SOURCE} macro is defined, it enables code that
> +validates inputs passed to some functions in @theglibc to determine if
> +they are safe.  If the compiler is unable to determine that the inputs
> +to the function call are safe, the call may be replaced by a call to its
> +hardened variant that does additional safety checks at runtime.  Some
> +hardened variants need the size of the buffer to perform access
> +validation and this is provided by the @code{__builtin_object_size} or
> +the @code{__builtin_dynamic_object_size} builtin functions.
> +
> +At runtime, if any of those safety checks fail, the program will
> +terminate with a @code{SIGABRT} signal.  @code{_FORTIFY_SOURCE} may be
> +defined to one of the following values:
> +
> +@itemize @bullet
> +@item @math{1}: This enables buffer bounds checking using the value
> +returned by the @code{__builtin_object_size} compiler builtin function.
> +If the function returns @code{(size_t) -1}, the function call is left
> +untouched.  Additionally, this level also enables validation of flags to
> +the @code{open}, @code{open64}, @code{openat} and @code{openat64}
> +functions.
> +
> +@item @math{2}: This behaves like @math{1}, with the addition of some
> +checks that may trap code that is conforming but unsafe, e.g. accepting
> +@code{%n} only in read-only format strings.
> +
> +@item @math{3}: This enables buffer bounds checking using the value
> +returned by the @code{__builtin_dynamic_object_size} compiler builtin
> +function.  If the function returns @code{(size_t) -1}, the function call
> +is left untouched.  Fortification at this level may have a impact on
> +program performance if the function call that is fortified is frequently
> +encountered and the size expression returned by
> +@code{__builtin_dynamic_object_size} is complex.
> +@end itemize
> +

Regards.

-- 
Yann Droneaud
OPTEYA