From b22b6216997022c19bea7afde977fd6360c8a2bf Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 17 Nov 2018 05:14:10 -0600 Subject: [PATCH] Improve some of the documentation related to security --- README.rst | 81 ++++++++++++++++++++++++++++------------ examples/development.ini | 6 +++ examples/pgwui.ini | 6 +++ 3 files changed, 69 insertions(+), 24 deletions(-) diff --git a/README.rst b/README.rst index 1d33b23..f794c6e 100644 --- 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 ca63bc6..d3d1b91 100644 --- 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 b9cc82f..12ce68d 100644 --- 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 -- 2.34.1