OpenE2K/gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[Ada] Tweaks to hardening docs

Browse Source 
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.
This commit is contained in:
Alexandre Oliva 2022-04-21 00:17:28 -03:00 committed by Pierre-Marie de Rodat
parent 4609660b77
commit 33dec214f0
2 changed files with 79 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
gcc/ada/doc/gnat_rm/security_hardening_features.rst
View File

@ -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.

49
gcc/ada/gnat_rm.texi
View File

@ -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