Improve some of the documentation related to security

diff --git a/README.rst b/README.rst
index 1d33b23c9ca363d180b09d1c1987fd1ee17e0be5..f794c6e804aa62dc0ff13b0e012314603b2481d9 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -38,6 +38,11 @@ simple and stand-alone.  More advanced users may use PGWUI_Server's
 WSGI interface to connect to a more full-featured webserver such as
 Apache or Nginx.
 
+PGWUI_Server does not support HTTPS out-of-the-box.  It is designed to
+stand behind a reverse web proxy or an advanced WSGI web server which
+is expected to supply this functionality.  Nginx, Apache, and many
+other full-featured web servers are all suitable.
+
 PGWUI_Server supports configuration using a traditional *.ini* file.
 
 
@@ -88,30 +93,58 @@ Putting PGWUI on the Internet
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The default configuration does not expose the website to the network.
-Of course this can be reconfigured in the .ini file.  However,
-although it will work, exposing pserve/waitress to the Internet is not
-recommended.  Use a reverse web proxy instead, or configure your
-webserver of choice to talk with PGWUI via WSGI.
-
-`Nginx`_ is often the simplest, and best, choice for an
-Internet-facing, reverse proxy, web server.  A useful reverse-proxy
-configuration to connect the default WSGI server to the Internet might
-be::
-
-    location / {
-        proxy_pass       http://localhost:6543;
-        proxy_set_header Host      $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-
-For more information see the `Nginx`_ documentation.
-
-It is beyond the scope of this documentation to describe how to use
-PGWUI_Server's WSGI support.  Any WSGI web server can be used with
-PGWUI_Server, with or without reverse-proxying.
-
-"pserve" does not support HTTPS.  Consult your webserver documentation
-for HTTPS support.
+Of course this can be reconfigured in the .ini file.  Although it will
+work, using unsecured communications and exposing pserve/waitress to
+the Internet, or even the local network, is not recommended.  Use a
+reverse web proxy to talk with PGWUI_Server instead, or configure your
+webserver of choice to talk with PGWUI_Server via WSGI.
+
+PGWUI_Server does not secure network communications in *any* way.  A
+connection between the PGWUI_Server application and a full-featured
+webserver is required to layer HTTPS with TLS encryption over
+PGWUI_Server's network traffic.  This layering is necessary to provide
+privacy, identity validation, and data integrity.
+
+This document gives minimal guidance in connecting PGWUI_Server to a
+full-featured webserver.  There is no difference between connecting
+PGWUI_Server to a webserver and connecting any other WSGI
+application. And there is no difference between reverse-proxying to
+PGWUI_Server and reverse-proxying to any other web-based application.
+Details will vary based on the full-featured webserver selected.  Any
+feature-full webserver will work.  Additional guidance in obtaining
+suitable SSL certificates, using them on a webserver, WSGI
+connectivity, reverse web proxying, webserver configuration, securing
+web traffic with HTTPS, and many other web related system
+administration basics and network security essentials, are beyond the
+scope of this document.
+
+`Nginx`_ is often the simplest, and best, choice for a secure
+Internet-facing, reverse proxy, web server.  A useful `Nginx`_
+reverse-proxy configuration which connects PGWUI_Server's default WSGI
+server to the Internet might be::
+
+        location / {
+            proxy_pass       http://localhost:6543;
+            # Using $http_host relies on the client, but is useful
+            # because it preserves the original URL's port when
+            # ssh tunneling.  If the client does not send the HOST
+            # header than it may be necessary to use $host instead.
+            proxy_set_header Host      $http_host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_redirect default;
+       }
+
+Replace the ``location / { ... }`` section appearing in the default
+`Nginx`_ configuration with the above.  For more information see the
+`Nginx`_ documentation.
+
+It is beyond the scope of this document to describe how to use
+PGWUI_Server's WSGI support, or the nuances of reverse-proxy
+configuration.  Any WSGI web server can be used with PGWUI_Server, as
+can any reverse web-proxy.
+
+Again, ``pserve`` with ``waitress`` does not support HTTPS.  Consult your
+webserver's documentation for HTTPS support.
 
 
 Configuration

diff --git a/examples/development.ini b/examples/development.ini
index ca63bc61d5aa1505d2fd25f3fd6660e2673e78d6..d3d1b915f1c7306e20c8239f11c0040a281bda80 100644 (file)
--- a/examples/development.ini
+++ b/examples/development.ini
@@ -133,6 +133,12 @@ session.cookie_on_exception = True
 
 [server:main]
 use = egg:waitress#main
+
+# A value for "host" of "*", instead of "127.0.0.1", exposes the
+# application to the network.  Unless you trust everyone and every
+# device that might access your network this will, at minimum, expose
+# what could be highly sensitive information.  See the documentation
+# for more secure alternatives.
 host = 127.0.0.1
 port = 6543
 

diff --git a/examples/pgwui.ini b/examples/pgwui.ini
index b9cc82ffbdb0cd352b4178c7b0094474e9587b8b..12ce68df2518f78858ccfe28ed9eb005ac0e9ee6 100644 (file)
--- a/examples/pgwui.ini
+++ b/examples/pgwui.ini
@@ -133,6 +133,12 @@ session.cookie_on_exception = True
 #     }
 #
 use = egg:waitress#main
+
+# A value for "host" of "*", instead of "127.0.0.1", exposes the
+# application to the network.  Unless you trust everyone and every
+# device that might access your network this will, at minimum, expose
+# what could be highly sensitive information.  See the documentation
+# for more secure alternatives.
 host = 127.0.0.1
 port = 6543