public inbox for gcc-cvs@sourceware.org help / color / mirror / Atom feed
From: Pierre-Marie de Rodat <pmderodat@gcc.gnu.org> To: gcc-cvs@gcc.gnu.org Subject: [gcc r13-831] [Ada] Tweaks to hardening docs Date: Mon, 30 May 2022 08:30:21 +0000 (GMT) [thread overview] Message-ID: <20220530083021.F154C3815FFA@sourceware.org> (raw) https://gcc.gnu.org/g:33dec214f0270ac86c445e08c32843b73e44fb23 commit r13-831-g33dec214f0270ac86c445e08c32843b73e44fb23 Author: Alexandre Oliva <oliva@adacore.com> 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
reply other threads:[~2022-05-30 8:30 UTC|newest] Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20220530083021.F154C3815FFA@sourceware.org \ --to=pmderodat@gcc.gnu.org \ --cc=gcc-cvs@gcc.gnu.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).