diff --git a/omero/sysadmins/client-server-ssl.rst b/omero/sysadmins/client-server-ssl.rst index 4d48d24cb6..464ffc5b8e 100644 --- a/omero/sysadmins/client-server-ssl.rst +++ b/omero/sysadmins/client-server-ssl.rst @@ -8,14 +8,19 @@ 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 `_ 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 `_ 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 @@ -23,19 +28,15 @@ Copy :file:`server.p12` to the OMERO.server host, for instance to :file:`/etc/ss 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. diff --git a/omero/sysadmins/server-upgrade.rst b/omero/sysadmins/server-upgrade.rst index 4c592c2f06..93ca702601 100644 --- a/omero/sysadmins/server-upgrade.rst +++ b/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 `_. 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 `_ 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 `_. + +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 ^^^^^^^^^^^^^^^^^^^ diff --git a/omero/sysadmins/troubleshooting.rst b/omero/sysadmins/troubleshooting.rst index 24eccec8f8..de7053a609 100644 --- a/omero/sysadmins/troubleshooting.rst +++ b/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 -`_ 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 `_ +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... ----------------------