From patchwork Tue Jan 10 13:40:23 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Siddhesh Poyarekar X-Patchwork-Id: 62892 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 6F63E3858416 for ; Tue, 10 Jan 2023 13:41:01 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 6F63E3858416 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1673358061; bh=yVAsS9Y0EYUyXcNGPTSQtAP0/K+Zx7xAAMi2hqAwRPk=; h=To:Cc:Subject:Date:In-Reply-To:References:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From:Reply-To:From; b=rRM4WvEE/uaufekPwJA1+a379iUV7BXksPRenXsvX+cVNvWlg4CtWixiPCSzO7Tvy yx8FdlBFyJGb+aq0mevFv/o6EBzmBKGHfnP35Yg37HYkpSnCoYqL7CYa8+XnqG2mFY GRgl5kfwB/hiP968hzf3C05bP+0AiTsYmYwVrCqo= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from butterfly.birch.relay.mailchannels.net (butterfly.birch.relay.mailchannels.net [23.83.209.27]) by sourceware.org (Postfix) with ESMTPS id 0C3C03858C52 for ; Tue, 10 Jan 2023 13:40:36 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 0C3C03858C52 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 1D9113E212F; Tue, 10 Jan 2023 13:40:35 +0000 (UTC) Received: from pdx1-sub0-mail-a307.dreamhost.com (unknown [127.0.0.6]) (Authenticated sender: dreamhost) by relay.mailchannels.net (Postfix) with ESMTPA id 859173E2211; Tue, 10 Jan 2023 13:40:34 +0000 (UTC) ARC-Seal: i=1; s=arc-2022; d=mailchannels.net; t=1673358034; a=rsa-sha256; cv=none; b=K3uJv4955mDZfHYSVv7GCroGnWYyQN/UGDBeERPW5o4GdwS3mSO3IyJRpiaSE8owNAu3DS u2Kn45VqSKP7JL57kCA3bQZ994sD3+BfaG+1+WcgldX4kErtPPA6UkBkfGWGDJ836EF/CE qTE6xQdMsuctHIwQYH1TSLyRN/hvGOTzyWoZjD3FM7LfowLv3m66emYzhRg33mdhZtOwB/ Ehcm8Bulbzph5bMK+cvES8UBngqRKaxIilqE+AlglW0E4MVwdA7xmdoipNVCPmN14dV8JN rvpxLAaaCaljVb9R6bm+DEhIkkjpau/gz/Q0ssQURk0lf3xurDiGlqRbY65hvQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=mailchannels.net; s=arc-2022; t=1673358034; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=yVAsS9Y0EYUyXcNGPTSQtAP0/K+Zx7xAAMi2hqAwRPk=; b=03dPlgiuda+ZMGjSOBgX4GZaIud25b2x+2ubUPVcg0eZBK8t4WTM7U1jG/GtIepzurXuNS 8rkQftYBrbznvYIxmu6MRByN1ZAwGsgSPHPc1upnaGMWZQKZENrKcPSGHZ09P7YbBhMFaK k/rHMEuXH0fqqHxukq7EYQDLd08zk1DvR4RrwED/mUxPC/o/2CJkNUgywM3eAuEvC0tMU/ 4+TzOnWpDCHZg910lEonHwYxNqQmDY54C30lKthecqQ/5OpzYK3d0VKlJ9mzBd0yrd1Sw8 +wxyFHGrlp+sJbGxgGbcORSK+ZIBGKUbnt/yfiLW6O1wST1x0UuQMzBaE3y04g== ARC-Authentication-Results: i=1; rspamd-6f569fcb69-jcxpq; 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-Lonely-Cure: 7f5bc5ac23369b65_1673358034955_3673082864 X-MC-Loop-Signature: 1673358034955:1933148890 X-MC-Ingress-Time: 1673358034955 Received: from pdx1-sub0-mail-a307.dreamhost.com (pop.dreamhost.com [64.90.62.162]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384) by 100.123.200.123 (trex/6.7.1); Tue, 10 Jan 2023 13:40:34 +0000 Received: from fedora.redhat.com (bras-base-toroon4834w-grc-23-76-68-24-147.dsl.bell.ca [76.68.24.147]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) (Authenticated sender: siddhesh@gotplt.org) by pdx1-sub0-mail-a307.dreamhost.com (Postfix) with ESMTPSA id 4NrsQ91QmgzQf; Tue, 10 Jan 2023 05:40:32 -0800 (PST) To: libc-alpha@sourceware.org Cc: fweimer@redhat.com Subject: [PATCH v4] Add _FORTIFY_SOURCE implementation documentation [BZ #28998] Date: Tue, 10 Jan 2023 08:40:23 -0500 Message-Id: <20230110134023.447253-1-siddhesh@sourceware.org> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221215162506.1802077-1-siddhesh@sourceware.org> References: <20221215162506.1802077-1-siddhesh@sourceware.org> MIME-Version: 1.0 X-Spam-Status: No, score=-1171.8 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 X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Siddhesh Poyarekar via Libc-alpha From: Siddhesh Poyarekar Reply-To: Siddhesh Poyarekar Errors-To: libc-alpha-bounces+patchwork=sourceware.org@sourceware.org Sender: "Libc-alpha" 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 --- Changes from v3: - Regenerate list and document the command - Document exceptions to printf, open, etc fortified variants 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 | 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