doc-txt updates for the security changes

3 files changed, 38 insertions, 2 deletions

diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index fe9c42a6e..386a15b8f 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -95,6 +95,9 @@ DW/26 Set FD_CLOEXEC on SMTP sockets after forking in the daemon, to ensure
 PP/27 Bugzilla 1047: change the default for system_filter_user to be the Exim
       run-time user, instead of root.
 
+PP/28 Add WHITELIST_D_MACROS option to let some macros be overriden by the
+      Exim run-time user without dropping privileges.
+
 
 Exim version 4.72
 -----------------
diff --git a/doc/doc-txt/IncompatibleChanges b/doc/doc-txt/IncompatibleChanges
index b578faa5b..8f07d784f 100644
--- a/doc/doc-txt/IncompatibleChanges
+++ b/doc/doc-txt/IncompatibleChanges
@@ -35,11 +35,25 @@ Exim version 4.73
    CONFIGURE_OWNER, which we discourage.  Exim now checks to ensure that
    files are not writable by other accounts.
 
- * ALT_CONFIG_ROOT_ONLY is no longer optional and is forced on; the Exim
-   user can no longer use -C/-D and retain privilege.
+ * The ALT_CONFIG_ROOT_ONLY build option is no longer optional and is forced
+   on; the Exim user can, by default, no longer use -C/-D and retain privilege.
+   Two new build options mitigate this.
+
+    * TRUSTED_CONFIG_PREFIX_LIST defines a path prefix within which files
+      owned by root can be used by the Exim user; this is the recommended
+      approach going forward.
+
+    * WHITELIST_D_MACROS defines a colon-separated list of macro names which
+      the Exim run-time user may safely pass without dropping privileges.
+      Because changes to this involve a recompile, this is not the recommended
+      approach but may ease transition.  The values of the macros, when
+      overriden, are constrained to match this regex: ^[A-Za-z0-9_/.-]*$
 
  * The system_filter_user option now defaults to the Exim run-time user,
    rather than root.  You can still set it explicitly to root and this
    can be done with prior versions too, letting you roll versions
    without needing to change this configuration option.
 
+ * ClamAV must be at least version 0.95 unless WITH_OLD_CLAMAV_STREAM is
+   defined at build time.
+
diff --git a/doc/doc-txt/NewStuff b/doc/doc-txt/NewStuff
index cedfc6e25..b9d88ff82 100644
--- a/doc/doc-txt/NewStuff
+++ b/doc/doc-txt/NewStuff
@@ -12,6 +12,9 @@ the documentation is updated, this file is reduced to a short list.
 Version 4.73
 ------------
 
+ NOTE: this version is not guaranteed backwards-compatible, please read the
+       items below carefully
+
  1. A new main configuration option, "openssl_options", is available if Exim
     is built with SSL support provided by OpenSSL.  The option allows
     administrators to specify OpenSSL options to be used on connections;
@@ -97,6 +100,22 @@ Version 4.73
 11. [POSSIBLE CONFIG BREAKAGE] The default value for system_filter_user is now
     the Exim run-time user, instead of root.
 
+12. [POSSIBLE CONFIG BREAKAGE] ALT_CONFIG_ROOT_ONLY is no longer optional and
+    is forced on.  This is mitigated by the new build option
+    TRUSTED_CONFIG_PREFIX_LIST which defines a list of pathname prefices which
+    are trusted; if a config file is owned by root and is under that prefix,
+    then it may be used by the Exim run-time user.
+
+13. [POSSIBLE CONFIG BREAKAGE] The Exim user is no longer automatically
+    trusted to supply -D<Macro[=Value]> overrides on the command-line.  Going
+    forward, we recommend using TRUSTED_CONFIG_PREFIX_LIST with shim configs
+    that include the main config.  As a transition mechanism, we are
+    temporarily providing a work-around: the new build option
+    WHITELIST_D_MACROS provides a colon-separated list of macro names which
+    may be overriden by the Exim run-time user.  The values of these macros
+    are constrained to the regex ^[A-Za-z0-9_/.-]*$ (which explicitly does
+    allow for empty values).
+
 
 Version 4.72
 ------------