--- wikisrc/pkgsrc/hardening.mdwn	2017/11/05 23:07:27	1.22
+++ wikisrc/pkgsrc/hardening.mdwn	2017/11/05 23:54:11	1.23
@@ -11,29 +11,60 @@ Mechanisms can be enabled individually i
 individually described below.  They are sorted by whether thery are
 enabled by default, and then by their ordering in mk/defaults/mk.conf.
 
+For each, 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.
+
 ## Enabled by default in the stable branch
 
-* `PKGSRC_USE_FORTIFY`: allows substitute wrappers to be used for commonly used
-  functions that do not bounds checking regularly - but could in some cases
-  (enabled by default since pkgsrc-2017Q3)
+### PKGSRC_USE_FORTIFY
+
+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.
+
+TODO: Explain FORTIFY_SOURCE 1 vs 2, and which is used.  Give a link
+to a good explanation of the technique.  Explain if this is gcc specific.
+
+It has been enabled by default since pkgsrc-2017Q3.
+
+### PKGSRC_USE_SSP
 
-* 'PKGSRC_USE_SSP`: enables a stack-smashing protection mitigation (enabled
-  by default where known supported since pkgsrc-2017Q3)
+This enables a stack-smashing protection mitigation.
+
+TODO: Give a link to a good explanation.  Explain if this is gcc
+specific or also works with other compilers.  Explain if it is C/C++ only.
+
+It is enabled by default where known supported since pkgsrc-2017Q3.
 
 ## Enabled by default in pkgsrc HEAD
 
 ## Not enabled by default
 
-* `PKGSRC_MKPIE`: forces the creation of PIE (Position Independent
-  Executables) when supported on the current platform.  With PIE
-  executables, a platform that supports ASLR will be able to randomize
-  the process layout.
+### PKGSRC_MKPIE
+
+This requests the 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, 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.
+
+TODO/check: PIE executables will only be built for toolchains that
+support PIE and operating systems known to support ASLR.  Currently,
+this means NetBSD 8 and later, i386 and amd64.
+
+### PKGSRC_USE_RELRO
+
+This also makes the exploitation of some security vulnerabilities more
+difficult in some cases.
 
-* `PKGSRC_USE_RELRO`: this also makes the exploitation of some security
-  vulnerabilities more difficult in some cases.
+### PKGSRC_USE_STACK_CHECK
 
-* `PKGSRC_USE_STACK_CHECK`: uses `-fstack-check` with GCC for another stack
-  protection mitigation.
+This uses `-fstack-check` with GCC for another stack protection
+mitigation.
 
 # Caveats