From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2206) id 053A139730DC; Tue, 10 Jan 2023 15:23:35 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 053A139730DC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1673364215; bh=ZxBu9MyvAtjC9trlkWrUwXNJZ0b/YgwhhzHzB4ycYfg=; h=From:To:Subject:Date:From; b=VSmX/VhcEGzuHd36r1YhOV9uhc/lcBiog1z86yRAwdi7M9yBGgsSzI/bdunFSSZHQ e5Bf9cIoKL4168wX14GIZZf3unqPH8LyDlmzUCnxTY6yxomUVvi0yPRCYXXzu58XtM sqgt8Sbx5biVNZYOEcPlblDId78UyFN4rqPKNTpU= Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: Siddhesh Poyarekar To: glibc-cvs@sourceware.org Subject: [glibc] Add _FORTIFY_SOURCE implementation documentation [BZ #28998] X-Act-Checkin: glibc X-Git-Author: Siddhesh Poyarekar X-Git-Refname: refs/heads/master X-Git-Oldrev: ae612c45efb5e34713859a5facf92368307efb6e X-Git-Newrev: 3d3a2911ba65e613eac878d8eb02a0aba4ad7651 Message-Id: <20230110152335.053A139730DC@sourceware.org> Date: Tue, 10 Jan 2023 15:23:35 +0000 (GMT) List-Id: https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=3d3a2911ba65e613eac878d8eb02a0aba4ad7651 commit 3d3a2911ba65e613eac878d8eb02a0aba4ad7651 Author: Siddhesh Poyarekar Date: Tue Jan 10 10:22:38 2023 -0500 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 Reviewed-by: Florian Weimer Diff: --- manual/creature.texi | 2 + manual/maint.texi | 249 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 251 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..76d4a1a147 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,254 @@ 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 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. 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 + +In general, the fortified variants of the function calls use the name of +the function with a @code{__} prefix and a @code{_chk} suffix. There +are some exceptions, e.g. the @code{printf} family of functions where, +depending on the architecture, one may also see fortified variants have +the @code{_chkieee128} suffix or the @code{__nldbl___} prefix to their +names. + +Another exception is the @code{open} family of functions, where their +fortified replacements have the @code{__} prefix and a @code{_2} suffix. +The @code{FD_SET}, @code{FD_CLR} and @code{FD_ISSET} macros use the +@code{__fdelt_chk} function on fortification. + +The following functions and macros are fortified in @theglibc{}: +@c Generated using the following command: +@c find . -name Versions | xargs grep -e "_chk;" -e "_2;" | +@c cut -d ':' -f 2 | sed 's/;/\n/g' | sed 's/ *//g' | grep -v "^$" | +@c sort -u | grep ^__ | +@c grep -v -e ieee128 -e __nldbl -e align_cpy -e "fdelt_warn" | +@c sed 's/__fdelt_chk/@item @code{FD_SET}\n\n@item @code{FD_CLR}\n\n@item @code{FD_ISSET}\n/' | +@c sed 's/__\(.*\)_\(chk\|2\)/@item @code{\1}\n/' + +@itemize @bullet + +@item @code{asprintf} + +@item @code{confstr} + +@item @code{dprintf} + +@item @code{explicit_bzero} + +@item @code{FD_SET} + +@item @code{FD_CLR} + +@item @code{FD_ISSET} + +@item @code{fgets} + +@item @code{fgets_unlocked} + +@item @code{fgetws} + +@item @code{fgetws_unlocked} + +@item @code{fprintf} + +@item @code{fread} + +@item @code{fread_unlocked} + +@item @code{fwprintf} + +@item @code{getcwd} + +@item @code{getdomainname} + +@item @code{getgroups} + +@item @code{gethostname} + +@item @code{getlogin_r} + +@item @code{gets} + +@item @code{getwd} + +@item @code{longjmp} + +@item @code{mbsnrtowcs} + +@item @code{mbsrtowcs} + +@item @code{mbstowcs} + +@item @code{memcpy} + +@item @code{memmove} + +@item @code{mempcpy} + +@item @code{memset} + +@item @code{mq_open} + +@item @code{obstack_printf} + +@item @code{obstack_vprintf} + +@item @code{open} + +@item @code{open64} + +@item @code{openat} + +@item @code{openat64} + +@item @code{poll} + +@item @code{ppoll64} + +@item @code{ppoll} + +@item @code{pread64} + +@item @code{pread} + +@item @code{printf} + +@item @code{ptsname_r} + +@item @code{read} + +@item @code{readlinkat} + +@item @code{readlink} + +@item @code{realpath} + +@item @code{recv} + +@item @code{recvfrom} + +@item @code{snprintf} + +@item @code{sprintf} + +@item @code{stpcpy} + +@item @code{stpncpy} + +@item @code{strcat} + +@item @code{strcpy} + +@item @code{strncat} + +@item @code{strncpy} + +@item @code{swprintf} + +@item @code{syslog} + +@item @code{ttyname_r} + +@item @code{vasprintf} + +@item @code{vdprintf} + +@item @code{vfprintf} + +@item @code{vfwprintf} + +@item @code{vprintf} + +@item @code{vsnprintf} + +@item @code{vsprintf} + +@item @code{vswprintf} + +@item @code{vsyslog} + +@item @code{vwprintf} + +@item @code{wcpcpy} + +@item @code{wcpncpy} + +@item @code{wcrtomb} + +@item @code{wcscat} + +@item @code{wcscpy} + +@item @code{wcsncat} + +@item @code{wcsncpy} + +@item @code{wcsnrtombs} + +@item @code{wcsrtombs} + +@item @code{wcstombs} + +@item @code{wctomb} + +@item @code{wmemcpy} + +@item @code{wmemmove} + +@item @code{wmempcpy} + +@item @code{wmemset} + +@item @code{wprintf} + +@end itemize + + @node Symbol handling @appendixsec Symbol handling in the GNU C Library