deegree#943 and deegree#942 Updating handbook with new section on how…

… to run deegree secure in production

deegree-services/deegree-webservices-handbook/src/main/sphinx/installation.rst

@@ -66,10 +66,57 @@ To shut deegree webservices down, switch back to the terminal window and press `
 .. tip::
   If you want to run deegree webservices on system startup automatically, consider installing `Apache Tomcat 8 <http://tomcat.apache.org>`_ as a system service. Afterwards, download the WAR version of deegree webservices and deploy it into your Tomcat installation (e.g. by copying the WAR file into the ``webapps`` folder). Consult the `Tomcat documentation <https://tomcat.apache.org/tomcat-8.5-doc/index.html>`_ for more information and options.
 
+-----------------
+Securing deegree
+-----------------
+Most weaknesses in deegree come from incorrect or inappropriate configuration. It is nearly always possible to make
+deegree more secure than the default out of the box configuration. The following documents best practices and recommendations on
+securing a production deegree server, whether it be hosted on a Windows or Unix based operating system.
+
+__________________
+Software Versions
+__________________
+
+The first step is to make sure you are running the latest stable releases of software:
+
+* Operating System including the latest updates and security patches
+* Java Runtime Environment (JRE) or JDK
+* Apache Tomcat, Jetty or your preferred Java Servlet container
+* Third-party libraries such as GDAL, JDBC driver, and
+* deegree webservices itself.
+
+.. tip::
+    If you are running Apache Tomcat we recommend that you read and apply all recommendations as documented in `Apache Tomcat Security Considerations <https://tomcat.apache.org/tomcat-8.5-doc/security-howto.html>`_.
+
+______________
+Encryption
+______________
+
+When operating deegree in a production environment enable HTTPS with SSL or TLS. Either enable HTTPS on your Java Servlet
+Container or operate it behind a web server such as Apache httpd oder NGINX.
+
+.. tip::
+    If you are running Apache Tomcat read the `SSL HowTo <http://tomcat.apache.org/tomcat-8.5-doc/ssl-howto.html>`_.
+
+______________________________________
+Securing deegree console and REST API
+______________________________________
+It is as a huge security problem to operate the deegree web app without setting a password for the deegree console.
+How to set the password for the deegree console is described in :ref:`anchor-configuration-basics`.
+The same applies to the deegree REST API. Since both transfer the credentials as clear text (with a little bit of
+obscurity) it is highly recommended to enable encryption on the protocol level as described above!
+For further information how to protect the deegree REST API read more in :ref:`anchor-configuration-restapi`.
+You should also consider to limit the access to both resources. Apply a filter by IP or hostname to only allow a subset
+of machines to connect and access the deegree console and REST API.
+
+.. warning::
+    The deegree console provides access to the server file system. Therefore you must not operate the Java Servlet container as root user! Furthermore you should consider to enable the Java Security Manager and define restrictive file permissions. [#f6]_
+
 .. rubric:: Footnotes
 
 .. [#f1] Oracle JDK 7 and earlier versions are not supported anymore, be aware that those versions are out of maintenance and reached End-of-life.
 .. [#f2] OpenJDK binaries are provided by `Azul Systems <https://www.azul.com/downloads/zulu/>`_ or `AdoptOpenJDK <https://adoptopenjdk.net>`_.
 .. [#f3] Requires an installation of Docker Community or Enterprise Edition, download Docker from `www.docker.com <https://www.docker.com/>`_.
 .. [#f4] A Java Servlet 2.5 compliant container is required. We recommend using the latest `Apache Tomcat 8 <http://tomcat.apache.org/>`_ release.
 .. [#f5] As of deegree 3.4.0 the ZIP distribution bundle is deprecated and the download links are removed from the website. Download the ZIP from the `Nexus repository <http://repo.deegree.org/content/groups/public/org/deegree/deegree-webservices-tomcat-bundle/>`_ instead.
+.. [#f6] How to run securely Java applications we recommend to follow the `Java Security Guidelines <https://docs.oracle.com/javase/8/docs/technotes/guides/security/index.html>`_ and for `Apache Tomcat the Security Manager HowTo <http://tomcat.apache.org/tomcat-8.5-doc/security-manager-howto.html>`_.

deegree-services/deegree-webservices-handbook/src/main/sphinx/intro.rst

@@ -18,7 +18,7 @@ Characteristics of deegree WFS
 
 deegree WFS is an implementation of the `OGC Web Feature Service specification <http://www.opengeospatial.org/standards/wfs>`_. Notable features:
 
-* Official OGC reference implementation fo WFS 1.1.0 and WFS 2.0.0 Simple
+* Official OGC reference implementation for WFS 1.1.0 and WFS 2.0.0 Simple
 * Implements WFS standards 1.0.0, 1.1.0 and 2.0.0 [#f1]_
 * Fully transactional (even for rich data models)
 * Supports KVP, XML and SOAP requests

deegree-services/deegree-webservices-handbook/src/main/sphinx/restapi.rst

@@ -11,9 +11,10 @@ deegree offers a REST like web interface to access and configure the deegree wor
 Setting up the interface
 ------------------------
 
-The servlet that handles the REST interface is already running if you use the standard ``web.xml`` deployment descriptor. For security reasons, you'll need to add a user with the role ``deegree`` to your Tomcat configuration, eg. by adding an appropriate line to the ``conf/tomcat-users.xml`` file.
+The servlet that handles the REST interface is already running if you use the standard ``web.xml`` deployment descriptor. For security reasons the REST API is only accessible after successful authentication against the servlet container.
+When using Apache Tomcat you'll need to add a user with the role ``deegree`` to your Tomcat configuration ``conf/tomcat-users.xml`` file.
 
-Once you did that, you can get an overview of available 'commands' by requesting ``http://localhost:8080/deegree-webservices/config``. You'll need to provide the username/password you configured in your Tomcat configuration.
+Once you did that, you can get an overview of available 'commands' by requesting ``http://localhost:8080/deegree-webservices/config``. You'll need to provide the username/password credentials you configured for every request within the HTTP header (HTTP BASIC authentication).
 
 Here's an example output::
 
@@ -42,7 +43,7 @@ Here's an example output::
    200 - ok
    403 - if you tried something you shouldn't have
    404 - if a file or directory needed to fulfill a request was not found
-   500 - if something serious went wrong on the server side
+   500 - if something seriously went wrong on the server side
 
 ----------------------------
 Detailed explanation