From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from chocolate.ash.relay.mailchannels.net (chocolate.ash.relay.mailchannels.net [23.83.222.35]) by sourceware.org (Postfix) with ESMTPS id 04E223858D1E for ; Tue, 3 Jan 2023 14:29:53 +0000 (GMT) X-Sender-Id: dreamhost|x-authsender|siddhesh@gotplt.org Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id 718155C16B3; Tue, 3 Jan 2023 14:29:50 +0000 (UTC) Received: from pdx1-sub0-mail-a305.dreamhost.com (unknown [127.0.0.6]) (Authenticated sender: dreamhost) by relay.mailchannels.net (Postfix) with ESMTPA id D60035C1D8C; Tue, 3 Jan 2023 14:29:49 +0000 (UTC) ARC-Seal: i=1; s=arc-2022; d=mailchannels.net; t=1672756189; a=rsa-sha256; cv=none; b=GzgxFgRf4ZweJtsbM1fohJExi/BgOtKLZKiVU32p0kiRg+eqkX55veMxni3L8LO3g3p0tI QL01IJ47HkbpH6xEHT9u264W+BCxO4WS4lmTFFIZMYdUmWWNDjOrtEaRGNuJQO+/a6Yj/i FEoDh6KytNCj9Jhzbx7DfZFlhrepfsh0qgPnyVJIyu5KKSsrHsYZMkE8Ce8DIabkdI6BQg sbBiRDe+/XbJDu6ybJ0c3eAReUirIm80Bb07KgKSP8iprgEwALa6CgTh78o3p1u4e3HLL5 N4fRCo9eMG0NCanDQfTSC1rYG5QN0FXYVpNel75UBaBT5D5ZcNrq/tJ0sGq0Ng== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=mailchannels.net; s=arc-2022; t=1672756189; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=fSK4VfKXMkju9hp+erGXeSTiiGW0Kewl3iMv91V/TeI=; b=kIxUNjCAB0Dn2G9aXjDvl4rTmaWJ+BacZ1S96vJxsuDqnSuvtYeBwwZjFGXsHouLFDTkA7 twP+segw99uAwQ1jfyyCV1Pp1b6akSaVL2N6FQ/W9+YV90olOmt83fl523xtw8a9GrD8lN cigY7KHd0Nm0ARRnaLS62fsFbRkmt9P6EmWYe4ytmL3jFgQ+GB1GqCu3fDQp+5FtRb0NbN JjjXUxp8JQB6zdM2Us6VpiKm0PRDZ7MN3IC8xVm1FeXug+14zdVPG3HHTHeygp5KsJ5oO8 PhX/c5l0Wk7Cuo3VBt48oeLmneiQ3nSNZ5Kv6nXkwYDvsJTJ8gTmQZJC1Y7qDw== ARC-Authentication-Results: i=1; rspamd-896578cf5-mg9lk; auth=pass smtp.auth=dreamhost smtp.mailfrom=siddhesh@sourceware.org X-Sender-Id: dreamhost|x-authsender|siddhesh@gotplt.org X-MC-Relay: Neutral X-MailChannels-SenderId: dreamhost|x-authsender|siddhesh@gotplt.org X-MailChannels-Auth-Id: dreamhost X-Eyes-Dime: 5ccaae014358a77b_1672756190258_325986732 X-MC-Loop-Signature: 1672756190258:2626060431 X-MC-Ingress-Time: 1672756190258 Received: from pdx1-sub0-mail-a305.dreamhost.com (pop.dreamhost.com [64.90.62.162]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384) by 100.99.229.10 (trex/6.7.1); Tue, 03 Jan 2023 14:29:50 +0000 Received: from [192.168.0.182] (bras-base-toroon4834w-grc-23-76-68-24-147.dsl.bell.ca [76.68.24.147]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) (Authenticated sender: siddhesh@gotplt.org) by pdx1-sub0-mail-a305.dreamhost.com (Postfix) with ESMTPSA id 4NmZrF1X9Cz55; Tue, 3 Jan 2023 06:29:49 -0800 (PST) Message-ID: <2b0f4ba3-3856-2b8f-c429-91a5e798ba32@sourceware.org> Date: Tue, 3 Jan 2023 09:29:47 -0500 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.5.0 Subject: [ping][PATCH v3] Add _FORTIFY_SOURCE implementation documentation [BZ #28998] Content-Language: en-US To: libc-alpha@sourceware.org Cc: fweimer@redhat.com References: <20221215162506.1802077-1-siddhesh@sourceware.org> <20221222160403.4151387-1-siddhesh@sourceware.org> From: Siddhesh Poyarekar In-Reply-To: <20221222160403.4151387-1-siddhesh@sourceware.org> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-1172.1 required=5.0 tests=BAYES_00,GIT_PATCH_0,KAM_DMARC_NONE,KAM_DMARC_STATUS,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_SOFTFAIL,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: 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 > --- > 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 >