Merge pull request #2346 from sbesson/server_certificates_upgrade

Server certificates: review of upgrade & troubleshooting sections

omero/sysadmins/client-server-ssl.rst

@@ -8,34 +8,35 @@ OMERO.server and clients do not automatically support host verification, so a
 is possible.
 This may result in users inadvertently transmitting their login credentials to an attacker.
 
-This can be remedied by configuring OMERO.server with a certificate (the same certificate used for OMERO.web Nginx may work), and ensuring all OMERO clients are configured to verify the server certificate before connecting.
+This can be remedied by configuring OMERO.server with a certificate and ensuring all OMERO clients are configured to verify the server certificate before connecting.
 
 
 Server certificate
 ------------------
 
-The easiest solution is to re-use the SSL certificates used to protect OMERO.web.
-First convert the public certificate :file:`server.pem` and private key :file:`server.key` to the PKCS12 format where ``secret`` is the password used to protect the combined output file :file:`server.p12`::
+The easiest solution is to use the `omero-certificates <https://github.com/ome/omero-certificates>`_ plugin to
+generate self-signed server certificates alongside their associated configuration.
+This workflow is described in the particular sections of :doc:`unix/server-installation` documentation.
+
+Here we describe an alternative option to the usage of the `omero-certificates <https://github.com/ome/omero-certificates>`_ plugin. This option is re-using the SSL certificates used to protect OMERO.web. First convert
+the public certificate :file:`server.pem` and private key :file:`server.key`
+to the PKCS12 format where ``secret`` is the password used to protect the combined output file :file:`server.p12`::
 
     openssl pkcs12 -export -out server.p12 -in server.pem -inkey server.key -passout pass:secret
 
 Copy :file:`server.p12` to the OMERO.server host, for instance to :file:`/etc/ssl/omero/`.
 
 External access to OMERO.server is managed by the Glacier2 component which can be configured as follows::
 
-    # Enable authenticating ciphers.
-    omero config set omero.glacier2.IceSSL.Ciphers "ADH:HIGH:!LOW:!MD5:!EXP:!3DES:@STRENGTH"
+    omero config set omero.glacier2.IceSSL.Ciphers HIGH
     # Look for certificates in this directory, you can omit and use the full path to files instead
     omero config set omero.glacier2.IceSSL.DefaultDir /etc/ssl/omero/
     omero config set omero.glacier2.IceSSL.CertFile server.p12
     omero config set omero.glacier2.IceSSL.Password secret
-
-For even stronger security require TLS 1.2, disable anonymous ciphers and only allow ``HIGH``::
-
     omero config set omero.glacier2.IceSSL.Protocols tls1_2
     omero config set omero.glacier2.IceSSL.ProtocolVersionMin tls1_2
     omero config set omero.glacier2.IceSSL.ProtocolVersionMax tls1_2
-    omero config set omero.glacier2.IceSSL.Ciphers HIGH
+
 
 Restart OMERO.server.
 

omero/sysadmins/server-upgrade.rst

@@ -320,13 +320,42 @@ up to date to ensure that security updates are applied:
       $ # first, activate virtualenv where omero-py is installed. Then upgrade:
       $ pip install --upgrade 'omero-py>=\ |version_py|'
 
+.. _server_certificates:
 
 Server certificate
 ^^^^^^^^^^^^^^^^^^
-Since OMERO 5.6.2,  the recommended way to ensure that all OMERO server installations have, at minimum, a self-signed certificate is to use the `OMERO server certificate management plugin <https://github.com/ome/omero-certificates>`_. The plugin will generate or update your self-signed certificates and configure the OMERO.server. For the configuration to take effect, the server needs to be restarted.
+
+The server should be configured with at least a self-signed certificate to allow
+clients to establish secure connections.
+
+Since OMERO 5.6.2, the recommended way to ensure that all OMERO server installations have
+at minimum, a self-signed certificate is to use the
+`omero-certificates <https://pypi.org/project/omero-certificates/>`_ plugin.
+The plugin will generate or update your self-signed certificates and configure the OMERO.server.
+For the configuration to take effect, the server needs to be restarted.
 If you prefer to configure the OMERO server certificate manually, check
 :doc:`/sysadmins/client-server-ssl`.
-In OMERO.py version 5.13.0, the Anonymous Diffie-Hellman (ADH) default configuration has been removed. Please ensure that self-signed certificates have been generated and the OMERO.server configured accordingly.
+
+If your server has been configured with a version of ``omero-certificates`` older than
+0.3.0 or manually, the configuration may need to be upgraded in particular to
+disallow the `deprecated TLS 1.0 and 1.1 protocols <https://datatracker.ietf.org/doc/html/rfc8996>`_.
+
+To do so, activate the virtual environment where the server Python dependencies are installed,
+upgrade ``omero-certificates`` to version 0.3.0 or later, remove the
+:property:`omero.glacier2.IceSSL.Protocols` and :property:`omero.glacier2.IceSSL.ProtocolVersionMax`
+configurations and finally re-execute the :program:`omero certificates` command::
+
+    $ pip install "omero-certificates>=0.3"
+    $ omero config set omero.glacier2.IceSSL.Protocols
+    $ omero config set omero.glacier2.IceSSL.ProtocolVersionMax
+    $ omero certificates
+
+.. note::
+
+   From version 0.3.0, the :program:`omero certificates` command adds TLS 1.3 to the list of
+   TLS protocols allowed assuming the OMERO.server enviroment supports the protocol.
+   In order to negotiate this protocol, clients will also need to be upgraded to depend
+   on ``omero-blitz`` 5.7.0 or greater (Java) or ``omero-py`` 5.15.0 or greater (Python).
 
 Restart your server
 ^^^^^^^^^^^^^^^^^^^

omero/sysadmins/troubleshooting.rst

@@ -155,21 +155,23 @@ Please see the :doc:`/sysadmins/server-security` page for more information.
 SSL connection issues
 ^^^^^^^^^^^^^^^^^^^^^
 
-Deployment platforms show a trend of making the transport layer security
-policy tighter by default. The recommended way to overcome SSL
-connection issues for OMERO clients connecting to the server is to
-employ the `omero-certificates
-<https://pypi.org/project/omero-certificates/>`_ plugin available from
-PyPI_:
-
-.. literalinclude:: unix/walkthrough/walkthrough_debian10.sh
-    :start-after: #start-seclevel
-    :end-before: #end-seclevel
-
-Restart the OMERO.server as normal for the changes to take effect.
-
-An alternative approach is to add the parameter ``@SECLEVEL=0`` to the
-server SSL configuration.
+ - ``javax.net.ssl.SSLHandshakeException: DH ServerKeyExchange does not comply to algorithm constraints``
+ - ``javax.net.ssl.SSLHandshakeException: The server selected protocol version TLS10 is not accepted by client preferences [TLS12]``
+ - ``SSL handshake failure: The parameter is incorrect.``
+ - ``reason = SSL error occurred for new outgoing connection: remote address = XXX.XXX.XXX.XXX:4064 dh key too small``
+
+These errors indicate the client is unable to establish a secure connection
+with the server. Deployment platforms show a trend of making the transport
+layer security policy tighter by default.
+
+The recommended way to overcome SSL connection issues for OMERO clients
+connecting to the server is to use the
+`omero-certificates <https://pypi.org/project/omero-certificates/>`_
+plugin available from PyPI_.
+
+Follow the instructions from :ref:`server_certificates` to create and
+configure self-signed certificates as necessary on the OMERO.server and
+restart it as normal for the changes to take effect.
 
 Server crashes with...
 ----------------------