From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1914) id F154C3815FFA; Mon, 30 May 2022 08:30:21 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org F154C3815FFA MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Pierre-Marie de Rodat To: gcc-cvs@gcc.gnu.org Subject: [gcc r13-831] [Ada] Tweaks to hardening docs X-Act-Checkin: gcc X-Git-Author: Alexandre Oliva X-Git-Refname: refs/heads/master X-Git-Oldrev: 4609660b7739c85ee354da9c758c97f8ea2b998b X-Git-Newrev: 33dec214f0270ac86c445e08c32843b73e44fb23 Message-Id: <20220530083021.F154C3815FFA@sourceware.org> Date: Mon, 30 May 2022 08:30:21 +0000 (GMT) X-BeenThere: gcc-cvs@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 30 May 2022 08:30:22 -0000 https://gcc.gnu.org/g:33dec214f0270ac86c445e08c32843b73e44fb23 commit r13-831-g33dec214f0270ac86c445e08c32843b73e44fb23 Author: Alexandre Oliva Date: Thu Apr 21 00:17:28 2022 -0300 [Ada] Tweaks to hardening docs Mention when security hardening features are available in other languages. Expand the strub documentation a little, for clarity and completeness. Add missing 'aliased' and attribute to variables in strub example. gcc/ada/ * doc/gnat_rm/security_hardening_features.rst: Mention availability in other languages when applicable. (Stack Scrubbing): Associate the attribute with types, expand some comments, fix the example involving access to variables. * gnat_rm.texi: Regenerate. Diff: --- .../doc/gnat_rm/security_hardening_features.rst | 55 +++++++++++++++++----- gcc/ada/gnat_rm.texi | 49 ++++++++++++++----- 2 files changed, 79 insertions(+), 25 deletions(-) diff --git a/gcc/ada/doc/gnat_rm/security_hardening_features.rst b/gcc/ada/doc/gnat_rm/security_hardening_features.rst index 8c4c1f64a4e..0631a53df9b 100644 --- a/gcc/ada/doc/gnat_rm/security_hardening_features.rst +++ b/gcc/ada/doc/gnat_rm/security_hardening_features.rst @@ -31,9 +31,10 @@ option, to affect all subprograms in a compilation, and with a -- Before returning, Bar scrubs all call-clobbered registers. -For usage and more details on the command-line option, and on the -``zero_call_used_regs`` attribute, see :title:`Using the GNU Compiler -Collection (GCC)`. +For usage and more details on the command-line option, on the +``zero_call_used_regs`` attribute, and on their use with other +programming languages, see :title:`Using the GNU Compiler Collection +(GCC)`. .. Stack Scrubbing: @@ -44,14 +45,17 @@ Stack Scrubbing GNAT can generate code to zero-out stack frames used by subprograms. It can be activated with the :samp:`Machine_Attribute` pragma, on -specific subprograms and variables. +specific subprograms and variables, or their types. (This attribute +always applies to a type, even when it is associated with a subprogram +or a variable.) .. code-block:: ada function Foo returns Integer; pragma Machine_Attribute (Foo, "strub"); -- Foo and its callers are modified so as to scrub the stack - -- space used by Foo after it returns. + -- space used by Foo after it returns. Shorthand for: + -- pragma Machine_Attribute (Foo, "strub", "at-calls"); procedure Bar; pragma Machine_Attribute (Bar, "strub", "internal"); @@ -61,13 +65,16 @@ specific subprograms and variables. Var : Integer; pragma Machine_Attribute (Var, "strub"); -- Reading from Var in a subprogram enables stack scrubbing - -- of the stack space used by the subprogram. + -- of the stack space used by the subprogram. Furthermore, if + -- Var is declared within a subprogram, this also enables + -- scrubbing of the stack space used by that subprogram. There are also :switch:`-fstrub` command-line options to control default settings. For usage and more details on the command-line -option, and on the ``strub`` attribute, see :title:`Using the GNU -Compiler Collection (GCC)`. +option, on the ``strub`` attribute, and their use with other +programming languages, see :title:`Using the GNU Compiler Collection +(GCC)`. Note that Ada secondary stacks are not scrubbed. The restriction ``No_Secondary_Stack`` avoids their use, and thus their accidental @@ -81,16 +88,19 @@ access type designates a non-strub type. .. code-block:: ada - VI : Integer; + VI : aliased Integer; + pragma Machine_Attribute (VI, "strub"); XsVI : access Integer := VI'Access; -- Error. UXsVI : access Integer := VI'Unchecked_Access; -- OK, - -- UXsVI.all does not enable strub in the enclosing subprogram. + -- UXsVI does *not* enable strub in subprograms that + -- dereference it to obtain the UXsVI.all value. type Strub_Int is new Integer; pragma Machine_Attribute (Strub_Int, "strub"); - VSI : Strub_Int; - XsVSI : access Strub_Int := VSI'Access; -- OK. - -- XsVSI.all enables strub in the enclosing subprogram. + VSI : aliased Strub_Int; + XsVSI : access Strub_Int := VSI'Access; -- OK, + -- VSI and XsVSI.all both enable strub in subprograms that + -- read their values. Every access-to-subprogram type, renaming, and overriding and @@ -108,6 +118,9 @@ turned ``callable`` through such an explicit conversion: type TBar_Callable is access procedure; pragma Machine_Attribute (TBar_Callable, "strub", "callable"); + -- The attribute modifies the procedure type, rather than the + -- access type, because of the extra argument after "strub", + -- only applicable to subprogram types. Bar_Callable_Ptr : constant TBar_Callable := TBar_Callable (TBar'(Bar'Access)); @@ -115,6 +128,7 @@ turned ``callable`` through such an explicit conversion: procedure Bar_Callable renames Bar_Callable_Ptr.all; pragma Machine_Attribute (Bar_Callable, "strub", "callable"); + Note that the renaming declaration is expanded to a full subprogram body, it won't be just an alias. Only if it is inlined will it be as efficient as a call by dereferencing the access-to-subprogram constant @@ -162,6 +176,10 @@ respectively. They are separate options, however, because of the significantly different performance impact of the hardening transformations. +For usage and more details on the command-line options, see +:title:`Using the GNU Compiler Collection (GCC)`. These options can +be used with other programming languages supported by GCC. + .. Hardened Booleans: @@ -177,6 +195,7 @@ alternative representations, using representation clauses: for HBool use (16#5a#, 16#a5#); for HBool'Size use 8; + When validity checking is enabled, the compiler will check that variables of such types hold values corresponding to the selected representations. @@ -196,8 +215,14 @@ checked even when compiling with :switch:`-gnatVT`. pragma Machine_Attribute (HBool, "hardbool"); + Note that :switch:`-gnatVn` will disable even ``hardbool`` testing. +Analogous behavior is available as a GCC extension to the C and +Objective C programming languages, through the ``hardbool`` attribute. +For usage and more details on that attribute, see :title:`Using the +GNU Compiler Collection (GCC)`. + .. Control Flow Redundancy: @@ -243,3 +268,7 @@ disabled altogether. The instrumentation for hardening with control flow redundancy can be observed in dump files generated by the command-line option :switch:`-fdump-tree-hardcfr`. + +For more details on the control flow redundancy command-line options, +see :title:`Using the GNU Compiler Collection (GCC)`. These options +can be used with other programming languages supported by GCC. diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi index bf7c532a714..434bd3c8e61 100644 --- a/gcc/ada/gnat_rm.texi +++ b/gcc/ada/gnat_rm.texi @@ -21,7 +21,7 @@ @copying @quotation -GNAT Reference Manual , Apr 22, 2022 +GNAT Reference Manual , May 24, 2022 AdaCore @@ -28920,8 +28920,9 @@ pragma Machine_Attribute (Bar, "zero_call_used_regs", "all"); -- Before returning, Bar scrubs all call-clobbered registers. @end example -For usage and more details on the command-line option, and on the -@code{zero_call_used_regs} attribute, see @cite{Using the GNU Compiler Collection (GCC)}. +For usage and more details on the command-line option, on the +@code{zero_call_used_regs} attribute, and on their use with other +programming languages, see @cite{Using the GNU Compiler Collection (GCC)}. @c Stack Scrubbing: @@ -28933,13 +28934,16 @@ For usage and more details on the command-line option, and on the GNAT can generate code to zero-out stack frames used by subprograms. It can be activated with the @code{Machine_Attribute} pragma, on -specific subprograms and variables. +specific subprograms and variables, or their types. (This attribute +always applies to a type, even when it is associated with a subprogram +or a variable.) @example function Foo returns Integer; pragma Machine_Attribute (Foo, "strub"); -- Foo and its callers are modified so as to scrub the stack --- space used by Foo after it returns. +-- space used by Foo after it returns. Shorthand for: +-- pragma Machine_Attribute (Foo, "strub", "at-calls"); procedure Bar; pragma Machine_Attribute (Bar, "strub", "internal"); @@ -28949,12 +28953,15 @@ pragma Machine_Attribute (Bar, "strub", "internal"); Var : Integer; pragma Machine_Attribute (Var, "strub"); -- Reading from Var in a subprogram enables stack scrubbing --- of the stack space used by the subprogram. +-- of the stack space used by the subprogram. Furthermore, if +-- Var is declared within a subprogram, this also enables +-- scrubbing of the stack space used by that subprogram. @end example There are also @code{-fstrub} command-line options to control default settings. For usage and more details on the command-line -option, and on the @code{strub} attribute, see @cite{Using the GNU Compiler Collection (GCC)}. +option, on the @code{strub} attribute, and their use with other +programming languages, see @cite{Using the GNU Compiler Collection (GCC)}. Note that Ada secondary stacks are not scrubbed. The restriction @code{No_Secondary_Stack} avoids their use, and thus their accidental @@ -28967,16 +28974,19 @@ there is no way to express an access-to-strub type otherwise. access type designates a non-strub type. @example -VI : Integer; +VI : aliased Integer; +pragma Machine_Attribute (VI, "strub"); XsVI : access Integer := VI'Access; -- Error. UXsVI : access Integer := VI'Unchecked_Access; -- OK, --- UXsVI.all does not enable strub in the enclosing subprogram. +-- UXsVI does *not* enable strub in subprograms that +-- dereference it to obtain the UXsVI.all value. type Strub_Int is new Integer; pragma Machine_Attribute (Strub_Int, "strub"); -VSI : Strub_Int; -XsVSI : access Strub_Int := VSI'Access; -- OK. --- XsVSI.all enables strub in the enclosing subprogram. +VSI : aliased Strub_Int; +XsVSI : access Strub_Int := VSI'Access; -- OK, +-- VSI and XsVSI.all both enable strub in subprograms that +-- read their values. @end example Every access-to-subprogram type, renaming, and overriding and @@ -28993,6 +29003,9 @@ type TBar is access procedure; type TBar_Callable is access procedure; pragma Machine_Attribute (TBar_Callable, "strub", "callable"); +-- The attribute modifies the procedure type, rather than the +-- access type, because of the extra argument after "strub", +-- only applicable to subprogram types. Bar_Callable_Ptr : constant TBar_Callable := TBar_Callable (TBar'(Bar'Access)); @@ -29049,6 +29062,10 @@ respectively. They are separate options, however, because of the significantly different performance impact of the hardening transformations. +For usage and more details on the command-line options, see +@cite{Using the GNU Compiler Collection (GCC)}. These options can +be used with other programming languages supported by GCC. + @c Hardened Booleans: @node Hardened Booleans,Control Flow Redundancy,Hardened Conditionals,Security Hardening Features @@ -29086,6 +29103,10 @@ pragma Machine_Attribute (HBool, "hardbool"); Note that @code{-gnatVn} will disable even @code{hardbool} testing. +Analogous behavior is available as a GCC extension to the C and +Objective C programming languages, through the @code{hardbool} attribute. +For usage and more details on that attribute, see @cite{Using the GNU Compiler Collection (GCC)}. + @c Control Flow Redundancy: @node Control Flow Redundancy,,Hardened Booleans,Security Hardening Features @@ -29133,6 +29154,10 @@ The instrumentation for hardening with control flow redundancy can be observed in dump files generated by the command-line option @code{-fdump-tree-hardcfr}. +For more details on the control flow redundancy command-line options, +see @cite{Using the GNU Compiler Collection (GCC)}. These options +can be used with other programming languages supported by GCC. + @node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top @anchor{gnat_rm/obsolescent_features doc}@anchor{447}@anchor{gnat_rm/obsolescent_features id1}@anchor{448}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16} @chapter Obsolescent Features