[v3] Add _FORTIFY_SOURCE implementation documentation [BZ #28998]

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(+)

Ping!

On 2022-12-22 11:04, Siddhesh Poyarekar via Libc-alpha wrote:
> 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{}.  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
> +
> +The following functions are fortified in @theglibc{}:
> +
> +@itemize @bullet
> +@item @code{asprintf}: Replaced with @code{__asprintf_chk}.
> +
> +@item @code{confstr}: Replaced with @code{__confstr_chk}.
> +
> +@item @code{dprintf}: Replaced with @code{__dprintf_chk}.
> +
> +@item @code{explicit_bzero}: Replaced with @code{__explicit_bzero_chk}.
> +
> +@item @code{FD_SET}: Replaced with @code{__fdelt_chk}.
> +
> +@item @code{FD_CLR}: Replaced with @code{__fdelt_chk}.
> +
> +@item @code{FD_ISSET}: Replaced with @code{__fdelt_chk}.
> +
> +@item @code{fgets}: Replaced with @code{__fgets_chk}.
> +
> +@item @code{fgets_unlocked}: Replaced with @code{__fgets_unlocked_chk}.
> +
> +@item @code{fgetws}: Replaced with @code{__fgetws_chk}.
> +
> +@item @code{fgetws_unlocked}: Replaced with @code{__fgetws_unlocked_chk}.
> +
> +@item @code{fprintf}: Replaced with @code{__fprintf_chk}.
> +
> +@item @code{fread}: Replaced with @code{__fread_chk}.
> +
> +@item @code{fread_unlocked}: Replaced with @code{__fread_unlocked_chk}.
> +
> +@item @code{fwprintf}: Replaced with @code{__fwprintf_chk}.
> +
> +@item @code{getcwd}: Replaced with @code{__getcwd_chk}.
> +
> +@item @code{getdomainname}: Replaced with @code{__getdomainname_chk}.
> +
> +@item @code{getgroups}: Replaced with @code{__getgroups_chk}.
> +
> +@item @code{gethostname}: Replaced with @code{__gethostname_chk}.
> +
> +@item @code{getlogin_r}: Replaced with @code{__getlogin_r_chk}.
> +
> +@item @code{gets}: Replaced with @code{__gets_chk}.
> +
> +@item @code{getwd}: Replaced with @code{__getwd_chk}.
> +
> +@item @code{longjmp}: Replaced with @code{__longjmp_chk}.
> +
> +@item @code{mbsnrtowcs}: Replaced with @code{__mbsnrtowcs_chk}.
> +
> +@item @code{mbsrtowcs}: Replaced with @code{__mbsrtowcs_chk}.
> +
> +@item @code{mbstowcs}: Replaced with @code{__mbstowcs_chk}.
> +
> +@item @code{memcpy}: Replaced with @code{__memcpy_chk}.
> +
> +@item @code{memmove}: Replaced with @code{__memmove_chk}.
> +
> +@item @code{mempcpy}: Replaced with @code{__mempcpy_chk}.
> +
> +@item @code{memset}: Replaced with @code{__memset_chk}.
> +
> +@item @code{obstack_printf}: Replaced with @code{__obstack_printf_chk}.
> +
> +@item @code{obstack_vprintf}: Replaced with @code{__obstack_vprintf_chk}.
> +
> +@item @code{open}: Replaced with @code{__open_2}.
> +
> +@item @code{open64}: Replaced with @code{__open64_2}.
> +
> +@item @code{openat}: Replaced with @code{__openat_2}.
> +
> +@item @code{openat64}: Replaced with @code{__openat64_2}.
> +
> +@item @code{poll}: Replaced with @code{__poll_chk}.
> +
> +@item @code{ppoll}: Replaced with @code{__ppoll_chk}.
> +
> +@item @code{pread}: Replaced with @code{__pread_chk}.
> +
> +@item @code{pread64}: Replaced with @code{__pread64_chk}.
> +
> +@item @code{printf}: Replaced with @code{__printf_chk}.
> +
> +@item @code{ptsname_r}: Replaced with @code{__ptsname_r_chk}.
> +
> +@item @code{read}: Replaced with @code{__read_chk}.
> +
> +@item @code{readlink}: Replaced with @code{__readlink_chk}.
> +
> +@item @code{readlinkat}: Replaced with @code{__readlinkat_chk}.
> +
> +@item @code{realpath}: Replaced with @code{__realpath_chk}.
> +
> +@item @code{recv}: Replaced with @code{__recv_chk}.
> +
> +@item @code{recvfrom}: Replaced with @code{__recvfrom_chk}.
> +
> +@item @code{snprintf}: Replaced with @code{__snprintf_chk}.
> +
> +@item @code{sprintf}: Replaced with @code{__sprintf_chk}.
> +
> +@item @code{stpcpy}: Replaced with @code{__stpcpy_chk}.
> +
> +@item @code{stpncpy}: Replaced with @code{__stpncpy_chk}.
> +
> +@item @code{strcat}: Replaced with @code{__strcat_chk}.
> +
> +@item @code{strcpy}: Replaced with @code{__strcpy_chk}.
> +
> +@item @code{strncat}: Replaced with @code{__strncat_chk}.
> +
> +@item @code{strncpy}: Replaced with @code{__strncpy_chk}.
> +
> +@item @code{swprintf}: Replaced with @code{__swprintf_chk}.
> +
> +@item @code{syslog}: Replaced with @code{__syslog_chk}.
> +
> +@item @code{ttyname_r}: Replaced with @code{__ttyname_r_chk}.
> +
> +@item @code{vasprintf}: Replaced with @code{__vasprintf_chk}.
> +
> +@item @code{vdprintf}: Replaced with @code{__vdprintf_chk}.
> +
> +@item @code{vfprintf}: Replaced with @code{__vfprintf_chk}.
> +
> +@item @code{vfwprintf}: Replaced with @code{__vfwprintf_chk}.
> +
> +@item @code{vprintf}: Replaced with @code{__vprintf_chk}.
> +
> +@item @code{vsnprintf}: Replaced with @code{__vsnprintf_chk}.
> +
> +@item @code{vsprintf}: Replaced with @code{__vsprintf_chk}.
> +
> +@item @code{vswprintf}: Replaced with @code{__vswprintf_chk}.
> +
> +@item @code{vsyslog}: Replaced with @code{__vsyslog_chk}.
> +
> +@item @code{vwprintf}: Replaced with @code{__vwprintf_chk}.
> +
> +@item @code{wcpcpy}: Replaced with @code{__wcpcpy_chk}.
> +
> +@item @code{wcpncpy}: Replaced with @code{__wcpncpy_chk}.
> +
> +@item @code{wcrtomb}: Replaced with @code{__wcrtomb_chk}.
> +
> +@item @code{wcscat}: Replaced with @code{__wcscat_chk}.
> +
> +@item @code{wcscpy}: Replaced with @code{__wcscpy_chk}.
> +
> +@item @code{wcsncat}: Replaced with @code{__wcsncat_chk}.
> +
> +@item @code{wcsncpy}: Replaced with @code{__wcsncpy_chk}.
> +
> +@item @code{wcsnrtombs}: Replaced with @code{__wcsnrtombs_chk}.
> +
> +@item @code{wcsrtombs}: Replaced with @code{__wcsrtombs_chk}.
> +
> +@item @code{wcstombs}: Replaced with @code{__wcstombs_chk}.
> +
> +@item @code{wctomb}: Replaced with @code{__wctomb_chk}.
> +
> +@item @code{wmemcpy}: Replaced with @code{__wmemcpy_chk}.
> +
> +@item @code{wmemmove}: Replaced with @code{__wmemmove_chk}.
> +
> +@item @code{wmempcpy}: Replaced with @code{__wmempcpy_chk}.
> +
> +@item @code{wmemset}: Replaced with @code{__wmemset_chk}.
> +
> +@item @code{wprintf}: Replaced with @code{__wprintf_chk}.
> +
> +@end itemize
> +
> +
>   @node Symbol handling
>   @appendixsec Symbol handling in the GNU C Library
>

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.

On 2023-01-05 16:04, Yann Droneaud wrote:
>> +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.
> 

Thanks, I changed this to:

The @code{_FORTIFY_SOURCE} macro may be defined by users to control 
hardening of calls into some functions in @theglibc{}.  The definition 
should be at the top of the source file before any headers are included 
or at the pre-processor commandline using the @code{-D} switch.

Sid

* Siddhesh Poyarekar:

> +The following functions are fortified in @theglibc{}:
> +
> +@itemize @bullet
> +@item @code{asprintf}: Replaced with @code{__asprintf_chk}.
> +
> +@item @code{confstr}: Replaced with @code{__confstr_chk}.
> +
> +@item @code{dprintf}: Replaced with @code{__dprintf_chk}.

For the *printf* functions, the replacement depends on the architecture
and compilation mode (the concrete type of long double).

> +@item @code{explicit_bzero}: Replaced with @code{__explicit_bzero_chk}.
> +
> +@item @code{FD_SET}: Replaced with @code{__fdelt_chk}.
> +
> +@item @code{FD_CLR}: Replaced with @code{__fdelt_chk}.
> +
> +@item @code{FD_ISSET}: Replaced with @code{__fdelt_chk}.

These three macros (not functions) aren't replaced, but enhanced.

Maybe just mentioned the list of functions/macros, and point towards the
general pattern, but also note the presence of exceptions?

Rest looks okay to me.

Thanks,
Florian

On 2023-01-09 10:32, Florian Weimer wrote:
> * Siddhesh Poyarekar:
> 
>> +The following functions are fortified in @theglibc{}:
>> +
>> +@itemize @bullet
>> +@item @code{asprintf}: Replaced with @code{__asprintf_chk}.
>> +
>> +@item @code{confstr}: Replaced with @code{__confstr_chk}.
>> +
>> +@item @code{dprintf}: Replaced with @code{__dprintf_chk}.
> 
> For the *printf* functions, the replacement depends on the architecture
> and compilation mode (the concrete type of long double).

Oh yeah, I had missed the __nldbl_* ones and, TIL about the ieee128 
ones.  And guess what, I tried another way to look up this list (through 
Versions files) and found that mq_open is also fortified!

>> +@item @code{explicit_bzero}: Replaced with @code{__explicit_bzero_chk}.
>> +
>> +@item @code{FD_SET}: Replaced with @code{__fdelt_chk}.
>> +
>> +@item @code{FD_CLR}: Replaced with @code{__fdelt_chk}.
>> +
>> +@item @code{FD_ISSET}: Replaced with @code{__fdelt_chk}.
> 
> These three macros (not functions) aren't replaced, but enhanced.
> 
> Maybe just mentioned the list of functions/macros, and point towards the
> general pattern, but also note the presence of exceptions?

Ack, v4 coming up.

Thanks,
Sid

> On 22 Dec 2022, at 16:04, Siddhesh Poyarekar via Libc-alpha <libc-alpha@sourceware.org> wrote:
> 
> 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.
> 

Thanks for doing this, it looks great.

> Resolves: BZ #28998.
> Signed-off-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
> ---

best,
sam