git: 297bb39b6f0f - main - mitigations.7: move SSP documentation from security.7 to here

From: Ed Maste <emaste_at_FreeBSD.org>
Date: Sat, 01 Jun 2024 15:09:44 UTC
The branch main has been updated by emaste:

URL: https://cgit.FreeBSD.org/src/commit/?id=297bb39b6f0fcfc5d571dc77008eb7acf138d279

commit 297bb39b6f0fcfc5d571dc77008eb7acf138d279
Author:     Ed Maste <emaste@FreeBSD.org>
AuthorDate: 2024-06-01 12:07:38 +0000
Commit:     Ed Maste <emaste@FreeBSD.org>
CommitDate: 2024-06-01 15:09:30 +0000

    mitigations.7: move SSP documentation from security.7 to here
    
    Stack Smashing Protection (SSP) is a software vulnerability mitigation,
    and fits with this page.  Add a note to the beginning of security.7
    providing a more explicit cross reference to mitigations.7.
    
    Reviewed by:    kevans
    Sponsored by:   The FreeBSD Foundation
    Differential Revision: https://reviews.freebsd.org/D45435
---
 share/man/man7/mitigations.7 | 82 +++++++++++++++++++++++++++++++++++++++---
 share/man/man7/security.7    | 85 +++++---------------------------------------
 2 files changed, 87 insertions(+), 80 deletions(-)

diff --git a/share/man/man7/mitigations.7 b/share/man/man7/mitigations.7
index a322c9a917da..e5ff439455e3 100644
--- a/share/man/man7/mitigations.7
+++ b/share/man/man7/mitigations.7
@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 31, 2024
+.Dd June 1, 2024
 .Dt MITIGATIONS 7
 .Os
 .Sh NAME
@@ -54,8 +54,8 @@ Write XOR Execute page protection policy
 Relocation Read-Only (RELRO)
 .It
 Bind Now
-.\".It
-.\"Stack Smashing Protection (SSP)
+.It
+Stack Overflow Protection
 .It
 Supervisor Mode Memory Protection
 .It
@@ -232,7 +232,81 @@ preventing attacks on the relocation table.
 Note that this results in a nonstandard Application Binary Interface (ABI),
 and it is possible that some applications may not function correctly.
 .\"
-.\".Ss Stack Smashing Protection (SSP)
+.Ss Stack Overflow Protection
+.Fx
+supports stack overflow protection using the Stack Smashing Protector
+.Pq SSP
+compiler feature.
+In userland, SSP adds a per-process randomized canary at the end of every stack
+frame which is checked for corruption upon return from the function.
+In the kernel, a single randomized canary is used globally except on aarch64,
+which has a
+.Dv PERTHREAD_SSP
+.Xr config 8
+option to enable per-thread randomized canaries.
+If stack corruption is detected, then the process aborts to avoid potentially
+malicious execution as a result of the corruption.
+SSP may be enabled or disabled when building
+.Fx
+base with the
+.Xr src.conf 5
+SSP knob.
+.Pp
+When
+.Va WITH_SSP
+is enabled, which is the default, world is built with the
+.Fl fstack-protector-strong
+compiler option.
+The kernel is built with the
+.Fl fstack-protector
+option.
+.Pp
+In addition to SSP, a
+.Dq FORTIFY_SOURCE
+implementation is supported up to level 2 by defining
+.Va _FORTIFY_SOURCE
+to
+.Dv 1
+or
+.Dv 2
+before including any
+.Fx
+headers.
+.Fx
+world builds can set
+.Va FORTIFY_SOURCE
+to provide a default value for
+.Va _FORTIFY_SOURCE .
+When enabled,
+.Dq FORTIFY_SOURCE
+enables extra bounds checking in various functions that accept buffers to be
+written into.
+These functions currently have extra bounds checking support:
+.Bl -column -offset indent "snprintf" "memmove" "strncpy" "vsnprintf" "readlink"
+.It bcopy    Ta bzero    Ta fgets     Ta getcwd    Ta gets
+.It memcpy   Ta memmove  Ta memset    Ta read      Ta readlink
+.It snprintf Ta sprintf  Ta stpcpy    Ta stpncpy   Ta strcat
+.It strcpy   Ta strncat  Ta strncpy   Ta vsnprintf Ta vsprintf
+.El
+.Pp
+.Dq FORTIFY_SOURCE
+requires compiler support from
+.Xr clang 1
+or
+.Xr gcc 1 ,
+which provide the
+.Xr __builtin_object_size 3
+function that is used to determine the bounds of an object.
+This feature works best at optimization levels
+.Fl O1
+and above, as some object sizes may be less obvious without some data that the
+compiler would collect in an optimization pass.
+.Pp
+Similar to SSP, violating the bounds of an object will cause the program to
+abort in an effort to avoid malicious execution.
+This effectively provides finer-grained protection than SSP for some class of
+function and system calls, along with some protection for buffers allocated as
+part of the program data.
 .\"
 .Ss Supervisor mode memory protection
 Certain processors include features that prevent unintended access to memory
diff --git a/share/man/man7/security.7 b/share/man/man7/security.7
index 2e690e35d534..7cb906304861 100644
--- a/share/man/man7/security.7
+++ b/share/man/man7/security.7
@@ -26,13 +26,21 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd October 5, 2023
+.Dd June 1, 2024
 .Dt SECURITY 7
 .Os
 .Sh NAME
 .Nm security
 .Nd introduction to security under FreeBSD
 .Sh DESCRIPTION
+See
+.Xr mitigations 7
+for a description of vulnerability mitigations in
+.Fx .
+This man page documents other
+.Fx
+security related topics.
+.Pp
 Security is a function that begins and ends with the system administrator.
 While all
 .Bx
@@ -939,81 +947,6 @@ option that SSH allows in its
 .Pa authorized_keys
 file to make the key only usable to entities logging in from specific
 machines.
-.Sh STACK OVERFLOW PROTECTION
-.Fx
-supports stack overflow protection using the Stack Smashing Protector
-.Pq SSP
-compiler feature.
-In userland, SSP adds a per-process randomized canary at the end of every stack
-frame which is checked for corruption upon return from the function.
-In the kernel, a single randomized canary is used globally except on aarch64,
-which has a
-.Dv PERTHREAD_SSP
-.Xr config 8
-option to enable per-thread randomized canaries.
-If stack corruption is detected, then the process aborts to avoid potentially
-malicious execution as a result of the corruption.
-SSP may be enabled or disabled when building
-.Fx
-base with the
-.Xr src.conf 5
-SSP knob.
-.Pp
-When
-.Va WITH_SSP
-is enabled, which is the default, world is built with the
-.Fl fstack-protector-strong
-compiler option.
-The kernel is built with the
-.Fl fstack-protector
-option.
-.Pp
-In addition to SSP, a
-.Dq FORTIFY_SOURCE
-implementation is supported up to level 2 by defining
-.Va _FORTIFY_SOURCE
-to
-.Dv 1
-or
-.Dv 2
-before including any
-.Fx
-headers.
-.Fx
-world builds can set
-.Va FORTIFY_SOURCE
-to provide a default value for
-.Va _FORTIFY_SOURCE .
-When enabled,
-.Dq FORTIFY_SOURCE
-enables extra bounds checking in various functions that accept buffers to be
-written into.
-These functions currently have extra bounds checking support:
-.Bl -column -offset indent "snprintf" "memmove" "strncpy" "vsnprintf" "readlink"
-.It bcopy    Ta bzero    Ta fgets     Ta getcwd    Ta gets
-.It memcpy   Ta memmove  Ta memset    Ta read      Ta readlink
-.It snprintf Ta sprintf  Ta stpcpy    Ta stpncpy   Ta strcat
-.It strcpy   Ta strncat  Ta strncpy   Ta vsnprintf Ta vsprintf
-.El
-.Pp
-.Dq FORTIFY_SOURCE
-requires compiler support from
-.Xr clang 1
-or
-.Xr gcc 1 ,
-which provide the
-.Xr __builtin_object_size 3
-function that is used to determine the bounds of an object.
-This feature works best at optimization levels
-.Fl O1
-and above, as some object sizes may be less obvious without some data that the
-compiler would collect in an optimization pass.
-.Pp
-Similar to SSP, violating the bounds of an object will cause the program to
-abort in an effort to avoid malicious execution.
-This effectively provides finer-grained protection than SSP for some class of
-function and system calls, along with some protection for buffers allocated as
-part of the program data.
 .Sh KNOBS AND TWEAKS
 .Fx
 provides several knobs and tweak handles that make some introspection