Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Server certificates: review of upgrade & troubleshooting sections #2346

Merged
merged 9 commits into from
Sep 29, 2023
Merged

Server certificates: review of upgrade & troubleshooting sections #2346

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ace2892
OMERO server upgrade: add section about certificates upgrade
sbesson Sep 12, 2023
5c601e1
Client-server SSL: remove references to weak ciphers
sbesson Sep 12, 2023
cf79bca
Troubleshooting: add example of SSL handshake errors
sbesson Sep 12, 2023
da299f5
Switch to path operations to silence Sphinx 8 deprecation warnings
sbesson Sep 12, 2023
3df6c66
Update various markups
sbesson Sep 12, 2023
517c6a2
Rephrase note about TLS1.3
sbesson Sep 12, 2023
40f0db4
Revert "Switch to path operations to silence Sphinx 8 deprecation war…
sbesson Sep 13, 2023
ac23b7b
Address various suggestions raised during review
sbesson Sep 13, 2023
116f5cf
Apply suggestions from code review
sbesson Sep 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 10 additions & 9 deletions omero/sysadmins/client-server-ssl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
sbesson marked this conversation as resolved.
Show resolved Hide resolved
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 link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where would I run these commands, on my OMERO.web installation ? Where does the server.p12 live ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

server.p12 should live in a location defined by omero.glacier2.IceSSL.DefaultDir and accessible by OMERO.server.

This is probably one of the deviations with the plugin which will use a known location under the binary repository (/OMERO/certs) by default.


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.

Expand Down
33 changes: 31 additions & 2 deletions omero/sysadmins/server-upgrade.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
sbesson marked this conversation as resolved.
Show resolved Hide resolved
$ 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
^^^^^^^^^^^^^^^^^^^
Expand Down
32 changes: 17 additions & 15 deletions omero/sysadmins/troubleshooting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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...
----------------------
Expand Down