[pkgsrc/trunk]: pkgsrc/doc/guide/files guide: Add a hardening appendix, based...

[nia <nia%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/e5ba3f5ac01d
branches:  trunk
changeset: 459218:e5ba3f5ac01d
user:      nia <nia%pkgsrc.org@localhost>
date:      Fri Oct 01 17:20:27 2021 +0000

description:
guide: Add a hardening appendix, based on the wiki.

diffstat:

 doc/guide/files/Makefile      |    3 +-
 doc/guide/files/chapters.ent  |    3 +-
 doc/guide/files/hardening.xml |  629 ++++++++++++++++++++++++++++++++++++++++++
 doc/guide/files/pkgsrc.xml    |    5 +-
 4 files changed, 636 insertions(+), 4 deletions(-)

diffs (truncated from 697 to 300 lines):

diff -r 82d921509c68 -r e5ba3f5ac01d doc/guide/files/Makefile
--- a/doc/guide/files/Makefile  Fri Oct 01 16:32:04 2021 +0000
+++ b/doc/guide/files/Makefile  Fri Oct 01 17:20:27 2021 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.21 2020/06/20 05:31:10 rillig Exp $
+# $NetBSD: Makefile,v 1.22 2021/10/01 17:20:27 nia Exp $
 
 WEB_PREFIX?=           ${.CURDIR}/../htdocs
 DBX_XML_CATALOG?=      ${SGML_PREFIX}/docbook/4.5/catalog.xml
@@ -23,6 +23,7 @@
 SRCS+= fixes.xml
 SRCS+= ftp-layout.xml
 SRCS+= getting.xml
+SRCS+= hardening.xml
 SRCS+= help-devel.xml
 SRCS+= help-topics.xml
 SRCS+= help-user.xml
diff -r 82d921509c68 -r e5ba3f5ac01d doc/guide/files/chapters.ent
--- a/doc/guide/files/chapters.ent      Fri Oct 01 16:32:04 2021 +0000
+++ b/doc/guide/files/chapters.ent      Fri Oct 01 17:20:27 2021 +0000
@@ -1,7 +1,7 @@
 <!--
        Creates entities for each chapter in the pkgsrc book.
 
-       $NetBSD: chapters.ent,v 1.19 2019/04/28 15:22:24 rillig Exp $
+       $NetBSD: chapters.ent,v 1.20 2021/10/01 17:20:27 nia Exp $
 -->
 
 <!ENTITY chap.intro                    SYSTEM "introduction.xml">
@@ -41,6 +41,7 @@
 
 <!-- appendix -->
 <!ENTITY chap.examples                 SYSTEM "examples.xml">
+<!ENTITY chap.hardening                        SYSTEM "hardening.xml">
 <!ENTITY chap.logs                     SYSTEM "logs.xml">
 <!ENTITY chap.ftp-layout               SYSTEM "ftp-layout.xml">
 <!ENTITY chap.help-topics              SYSTEM "help-topics.xml">
diff -r 82d921509c68 -r e5ba3f5ac01d doc/guide/files/hardening.xml
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/guide/files/hardening.xml     Fri Oct 01 17:20:27 2021 +0000
@@ -0,0 +1,629 @@
+<!-- $NetBSD: hardening.xml,v 1.1 2021/10/01 17:20:27 nia Exp $ -->
+
+<appendix id="hardening">
+<title>Security hardening</title>
+
+<para>
+A number of mechanisms are available in pkgsrc to improve the security of the
+resulting system. This page describes the mechanisms, and gives hints
+about detecting and fixing problems.
+</para>
+
+<para>
+Mechanisms can be enabled individually in
+<filename>mk.conf</filename>, and are
+individually described below.
+</para>
+
+<para>
+Typically, a feature will cause some programs to fail to build or work
+when first enabled. This can be due to latent problems in the
+program, and can be due to other reasons. After enough testing to
+have confidence that user problems will be quite rare, individual
+mechanisms will be enabled by default.
+</para>
+
+<para>
+For each mechanism, see the Caveats section below for an explanation
+of what might go wrong at compile time and at run time, and how to
+notice and address these problems.
+</para>
+
+<sect1 id="hardening.mechanisms">
+<title>Mechanisms</title>
+
+<sect2 id="hardening.mechanisms.enabled">
+<title>Enabled by default</title>
+
+<sect3 id="hardening.mechanisms.enabled.fortify">
+<title>PKGSRC_USE_FORTIFY</title>
+
+<para>
+This allows substitute wrappers to be used for some commonly used
+library functions that do not have built-in bounds checking - but
+could in some cases.
+</para>
+
+<para>
+Two mitigation levels are available:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>"weak" only enables checks at compile-time.</para>
+</listitem>
+<listitem>
+<para>"strong" enables checks at compile-time and runtime.</para>
+</listitem>
+</itemizedlist>
+
+<para>
+"strong" has been enabled by default since pkgsrc-2017Q3.
+</para>
+</sect3>
+
+<sect3 id="hardening.mechanisms.enabled.ssp">
+<title>PKGSRC_USE_SSP</title>
+
+<para>
+This enables a stack-smashing protection mitigation. It is done by adding a
+guard variable to functions with vulnerable objects. The guards are initialized
+when a function is entered and then checked when the function exits. The guard
+check will fail and the program forcibly exited if the variable was modified in
+the meantime. This can happen in case of buffer overflows or memory corruption,
+and therefore exposing these bugs.
+</para>
+
+<para>
+Different mitigation levels are available:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>"yes", which will only protect functions considered vulnerable
+by the compiler;</para>
+</listitem>
+<listitem>
+<para>"all", which will protect every function;</para>
+</listitem>
+<listitem>
+<para>"strong", the default, which will apply a better balance between the
+two settings above.</para>
+</listitem>
+</itemizedlist>
+
+<para>
+This mitigation is supported by both GCC and clang. It may be supported in
+additional compilers, possibly under a different name. It is particularly useful
+for unsafe programming languages, such as C/C++.
+</para>
+
+<itemizedlist>
+<listitem>
+<para>"yes" is enabled by default where known supported since pkgsrc-2017Q3.</para>
+</listitem>
+<listitem>
+<para>"strong" is enabled by default where known supported since pkgsrc-2021Q4.</para>
+</listitem>
+</itemizedlist>
+
+<para>More details can be found here:</para>
+
+<itemizedlist>
+<listitem>
+<para>
+<ulink url="https://en.wikipedia.org/wiki/Buffer_overflow_protection";>Buffer overflow protection on Wikipedia</ulink>
+</para>
+</listitem>
+</itemizedlist>
+</sect3>
+
+<sect3 id="hardening.mechanisms.enabled.pie">
+<title>PKGSRC_MKPIE</title>
+
+<para>
+This requests the creation of PIE (Position Independent Executables) for all
+executables. The PIE mechanism is normally used for shared libraries, so that
+they can be loaded at differing addresses at runtime. PIE itself does not have
+useful security properties; however, it is necessary to fully leverage some,
+such as ASLR.  Some operating systems support Address Space Layout Randomization
+(ASLR), which causes different addresses to be used each time a program is run.
+This makes it more difficult for an attacker to guess addresses and thus makes
+exploits harder to construct. With PIE, ASLR can really be applied to the entire
+program, instead of the stack and heap only.
+</para>
+
+<para>
+PIE executables will only be built for toolchains that are known to support PIE.
+Currently, this means NetBSD on x86, ARM, SPARC64, m68k, and MIPS.
+</para>
+
+<para>
+<varname>PKGSRC_MKPIE</varname> was enabled by default after the pkgsrc-2021Q3 branch.
+</para>
+</sect3>
+
+<sect3 id="hardening.mechanisms.enabled.relro">
+<title>PKGSRC_USE_RELRO</title>
+
+<para>
+This also makes the exploitation of some security vulnerabilities more
+difficult in some cases.
+</para>
+
+<para>Two different mitigation levels are available:</para>
+
+<itemizedlist>
+<listitem>
+<para>
+partial: the ELF sections are reordered so that internal data sections
+precede the program's own data sections, and non-PLT GOT is read-only;
+</para>
+</listitem>
+<listitem>
+<para>
+full: in addition to partial RELRO, every relocation is performed immediately
+when starting the program (with a slight performance impact), allowing the
+entire GOT to be read-only.
+</para>
+</listitem>
+</itemizedlist>
+
+<para>
+This is currently supported by GCC. Many software distributions now enable this
+feature by default, at the "partial" level.
+</para>
+
+<para>
+More details can be found here:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>
+<ulink url="https://www.redhat.com/en/blog/hardening-elf-binaries-using-relocation-read-only-relro";>Hardening ELF binaries using Relocation Read-Only (RELRO)</ulink>
+</para>
+</listitem>
+</itemizedlist>
+</sect3>
+</sect2>
+
+<sect2 id="hardening.mechanisms.disabled">
+<title>Not enabled by default</title>
+
+<sect3 id="hardening.mechanisms.disabled.repro">
+<title>PKGSRC_MKREPRO</title>
+
+<para>
+With this option, pkgsrc will try to build packages reproducibly. This allows
+packages built from the same tree and with the same options, to produce
+identical results bit by bit. This option should be combined with ASLR and
+<varname>PKGSRC_MKPIE</varname> to avoid predictable address offsets for
+attackers attempting to exploit security vulnerabilities.
+</para>
+
+<para>
+More details can be found here:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>
+<ulink url="https://reproducible-builds.org/";>Reproducible Builds - a set of software development practices that create an independently-verifiable path from source to binary code</ulink>
+</para>
+</listitem>
+</itemizedlist>
+
+<para>
+More work likely needs to be done before pkgsrc is fully reproducible.
+</para>
+</sect3>
+
+<sect3 id="hardening.mechanisms.disabled.stackcheck">
+<title>PKGSRC_USE_STACK_CHECK</title>
+
+<para>
+This uses <literal>-fstack-check</literal> with GCC for
+another stack protection mitigation.
+</para>
+
+<para>
+It asks the compiler to generate code verifying that it does not corrupt the
+stack. According to GCC's manual page, this is really only useful for
+multi-threaded programs.
+</para>
+</sect3>
+</sect2>
+</sect1>
+
+<sect1 id="hardening.caveats">
+<title>Caveats</title>
+
+<sect2 id="hardening.caveats.pie">
+<title>Problems with PKGSRC_MKPIE</title>
+
+<sect3 id="hardening.caveats.pie.build">
+<title>Packages failing to build</title>
+
+<para>
+A number of packages may fail to build with this option enabled. The
+failures are often related to the absence of the <literal>-fPIC</literal>
+compilation flag when building libraries or executables (or ideally
+<literal>-fPIE</literal> in the latter case). This flag is added to the
+<varname>CFLAGS</varname> already, but requires the package to
+actually support it.
+</para>
+
+<sect4 id="hardening.caveats.pie.build.fix">
+<title>How to fix</title>
+