git: 8b5df7e36afb - stable/14 - mitigations.7: move SSP documentation from security.7 to here

From: Ed Maste <emaste_at_FreeBSD.org>
Date: Thu, 01 Aug 2024 14:47:18 UTC
The branch stable/14 has been updated by emaste:

URL: https://cgit.FreeBSD.org/src/commit/?id=8b5df7e36afb64617a0ff9e3692207537472a262

commit 8b5df7e36afb64617a0ff9e3692207537472a262
Author:     Ed Maste <emaste@FreeBSD.org>
AuthorDate: 2024-06-01 12:07:38 +0000
Commit:     Ed Maste <emaste@FreeBSD.org>
CommitDate: 2024-08-01 14:46:46 +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
    
    (cherry picked from commit 297bb39b6f0fcfc5d571dc77008eb7acf138d279)
---
 share/man/man7/mitigations.7 | 82 +++++++++++++++++++++++++++++++++++++++++---
 share/man/man7/security.7    | 10 +++++-
 2 files changed, 87 insertions(+), 5 deletions(-)

diff --git a/share/man/man7/mitigations.7 b/share/man/man7/mitigations.7
index db1b3244862b..4beaa4c9f46c 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 71107b29ba11..697d860a9836 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