Server certificates: review of upgrade & troubleshooting sections #2346

sbesson · 2023-09-12T17:06:52Z

Hopefully, this brings a conclusion to the great OMERO TLS saga of the Summer 2023 which was partly driven by this image.sc post ¹ and led to various OMERO component releases ² ³ ⁴ ⁵. This PR aims to amend the reference OMERO documentation to capture the new requirement in terms of OMERO.server certificates.

As a quick preamble, the problem space is complex as we are dealing with server/client connection issues across a set of environments spanning different versions (& sometimes compilation options) of OpenSSL, Java and Python. This complexity was demonstrated to some extent by the extent of the testing required in order to review, approve and release the set of changes aforementioned.

Probably as important as the code changes, we want to communicate efficiently the impact of these changes with the appropriate level of details/language e.g. end-users wants to understand why they cannot connect to the server or system administrators want to know about to upgrade the server without necessarily feeling they have to understand why ADH configurations have been removed.

This PR amends the three main sections of the reference documentation discussing SSL to capture the latest code/plugin improvements and remove unnecessary technical details:

the section about the server certificates in the OMERO.server upgrade page is supplemented with instructions about upgrading configurations created by old omero-certificates version
the client/server section is amended to remove all references to weak ciphers or security settings
the troubleshooting section is supplemented with concrete examples of SSL errors that could be received by an end-user and a link to the certificates section of the server upgrade page

A few notes:

one of the limitations for the ugprade section is to produce an easy answer to the question "do I need to modify my server SSL configuration?". The current approach as per ¹ and the upcoming OMERO.py 5.16.1 ⁶ is to teach various omero commands to print loud warnings about the outdated server-side SSL configurations
the Client Server SSL verification has been minimally changed but could possibly use a second round of review (outside the scope of this PR) especially for reviewing the validity the latter sections around certificate authority and client host verification. Arguably, this is the most relevant candidate for a reference page containing the technical details associated with SSL issues if this was deemed to be useful.

Critical feedback and suggestions very welcome in order to find the best wording

Also add reference to server certificate upgrade section

sbesson · 2023-09-12T21:02:06Z

Staged at the following URLs for review

https://omero--2346.org.readthedocs.build/en/2346/sysadmins/server-upgrade.html#server-certificate
https://omero--2346.org.readthedocs.build/en/2346/sysadmins/client-server-ssl.html
https://omero--2346.org.readthedocs.build/en/2346/sysadmins/troubleshooting.html#ssl-connection-issues

omero/sysadmins/server-upgrade.rst

jburel · 2023-09-13T11:58:18Z

omero/conf.py

@@ -392,8 +392,8 @@ def copy_legacy_redirects(app, exception):
    ]
    if app.builder.name == 'html':
        for html_src_path in redirect_files:
-            target_path = app.outdir + '/' + html_src_path
-            src_path = app.srcdir + '/' + html_src_path
+            target_path = (app.outdir / html_src_path)


broke job on merge-ci https://merge-ci.openmicroscopy.org/jenkins/job/OMERO-docs/221/

I'll revert da299f5. I originally thought this was the reason for the readthedocs CI failures.

Note the CI job is using Sphinx 7.1.x but the changes were introduced in Sphinx 7.2.0. So I suspect this codepath will need to be upgraded eventually alongside the version in OME CI. Is there a mechanism to use the same version as readhtedocs?

…nings" This reverts commit da299f5.

pwalczysko · 2023-09-14T18:52:14Z

omero/sysadmins/client-server-ssl.rst

+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.
+
+It is also possible to re-use the SSL certificates used to protect OMERO.web. First convert


Really unsure about 2 things:
Is the following paragraph describing how to re-use teh SSL certificates used to protect OMERO.web or, rather, as described above, is describing how to use the omero-certificates plugin ? If the former, where is a description about how to use the plugin ? Is the configuration example (using the Glacier2) described below valid for both ways ?

Is the following paragraph describing how to re-use teh SSL certificates used to protect OMERO.web or, rather, as described above, is describing how to use the omero-certificates plugin ?

To the best of my knowledge the former. Maybe we need to dwelve back into history here to understand the assumptions and make decisions:

this page was originally introduced in Client server SSL host verification #1942 in June 2019 on the OMERO 5.5.0 line

the initial work on omero-certificates and the first release was a year later in March 2020 - see https://github.com/ome/omero-certificates/releases/tag/0.1.0

So the content of this page has been largely superseded by the omero-certificates plugin which runs several of the commands from the Server certificate section under the hood. The only notable difference is that the Server certificate section explains how to re-use an existing public certificate/private key e.g. used by Nginx rather than generating a self-signed certificate like the plugin dows

If the former, where is a description about how to use the plugin ?

That's probably the key issue: there is no canonical place to the best of my knowledge. At the moment:

each of the server installation pages include a section explaining how to run the certificates - see https://omero.readthedocs.io/en/stable/sysadmins/unix/server-centos7-ice36.html#configuring-omero-server

this PR updates the section of the upgrade page to update the certificate settings

Is the configuration example (using the Glacier2) described below valid for both ways ?

Largely yes. This PR adjusts the example to make it compatible with the settings of the latest omero certificates

That makes sense, thank you.

pwalczysko · 2023-09-14T18:53:03Z

omero/sysadmins/client-server-ssl.rst

+
+It is also possible 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`::

    openssl pkcs12 -export -out server.p12 -in server.pem -inkey server.key -passout pass:secret


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

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.

pwalczysko · 2023-09-14T18:54:31Z

Some questions (maybe naive) in #2346 (comment) and #2346 (comment)

pwalczysko

See #2346 (comment)

sbesson · 2023-09-15T08:14:51Z

Some questions (maybe naive) in #2346 (comment) and #2346 (comment)

Thanks. A few responses inline. Overall these questions point at the mismatch between the content of this section of the documentation and the authoritative way of omero certificates in the rest of the documentation. Happy to follow OME's guidance on how to make things clearer.

omero/sysadmins/client-server-ssl.rst

pwalczysko · 2023-09-15T10:21:07Z

@sbesson Thank you for the clarifications. I think I understand and imho, the clarification for a more expert user (which is the target of this doc) should be sufficient after #2346 (comment) and #2346 (comment) are accepted.

Co-authored-by: pwalczysko <[email protected]>

sbesson added 3 commits September 12, 2023 17:03

OMERO server upgrade: add section about certificates upgrade

ace2892

Client-server SSL: remove references to weak ciphers

5c601e1

Troubleshooting: add example of SSL handshake errors

cf79bca

Also add reference to server certificate upgrade section

sbesson requested review from stick, chris-allan, jburel, pwalczysko, dominikl and khaledk2 September 12, 2023 17:06

Switch to path operations to silence Sphinx 8 deprecation warnings

da299f5

sbesson force-pushed the server_certificates_upgrade branch from 4fc049d to 8d24fbd Compare September 12, 2023 20:42

Update various markups

3df6c66

sbesson force-pushed the server_certificates_upgrade branch from 8d24fbd to 3df6c66 Compare September 12, 2023 20:49

Rephrase note about TLS1.3

517c6a2

jburel reviewed Sep 13, 2023

View reviewed changes

omero/sysadmins/server-upgrade.rst Outdated Show resolved Hide resolved

omero/sysadmins/server-upgrade.rst Show resolved Hide resolved

omero/sysadmins/server-upgrade.rst Outdated Show resolved Hide resolved

jburel reviewed Sep 13, 2023

View reviewed changes

sbesson added 2 commits September 13, 2023 13:00

Revert "Switch to path operations to silence Sphinx 8 deprecation war…

40f0db4

…nings" This reverts commit da299f5.

Address various suggestions raised during review

ac23b7b

pwalczysko reviewed Sep 14, 2023

View reviewed changes

pwalczysko requested changes Sep 14, 2023

View reviewed changes

pwalczysko reviewed Sep 15, 2023

View reviewed changes

omero/sysadmins/client-server-ssl.rst Outdated Show resolved Hide resolved

pwalczysko reviewed Sep 15, 2023

View reviewed changes

omero/sysadmins/client-server-ssl.rst Show resolved Hide resolved

Apply suggestions from code review

116f5cf

Co-authored-by: pwalczysko <[email protected]>

sbesson requested a review from pwalczysko September 15, 2023 14:02

pwalczysko approved these changes Sep 15, 2023

View reviewed changes

jburel merged commit 29b7988 into ome:develop Sep 29, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Server certificates: review of upgrade & troubleshooting sections #2346

Server certificates: review of upgrade & troubleshooting sections #2346

sbesson commented Sep 12, 2023

sbesson commented Sep 12, 2023

jburel Sep 13, 2023

sbesson Sep 13, 2023

jburel Sep 13, 2023

pwalczysko Sep 14, 2023 •

edited

Loading

sbesson Sep 15, 2023

pwalczysko Sep 15, 2023

pwalczysko Sep 14, 2023

sbesson Sep 15, 2023

pwalczysko commented Sep 14, 2023

pwalczysko left a comment

sbesson commented Sep 15, 2023

pwalczysko commented Sep 15, 2023

Server certificates: review of upgrade & troubleshooting sections #2346

Server certificates: review of upgrade & troubleshooting sections #2346

Conversation

sbesson commented Sep 12, 2023

Footnotes

sbesson commented Sep 12, 2023

jburel Sep 13, 2023

Choose a reason for hiding this comment

sbesson Sep 13, 2023

Choose a reason for hiding this comment

jburel Sep 13, 2023

Choose a reason for hiding this comment

pwalczysko Sep 14, 2023 • edited Loading

Choose a reason for hiding this comment

sbesson Sep 15, 2023

Choose a reason for hiding this comment

pwalczysko Sep 15, 2023

Choose a reason for hiding this comment

pwalczysko Sep 14, 2023

Choose a reason for hiding this comment

sbesson Sep 15, 2023

Choose a reason for hiding this comment

pwalczysko commented Sep 14, 2023

pwalczysko left a comment

Choose a reason for hiding this comment

sbesson commented Sep 15, 2023

pwalczysko commented Sep 15, 2023

pwalczysko Sep 14, 2023 •

edited

Loading