Skip to content

docs: OPENSSL_CONF workaround for TLS handshake on OpenSSL 3.5+#752

Merged
gijzelaerr merged 1 commit into
gijzelaerr:masterfrom
gridsociety:s7commplus-tls-openssl-doc
Jun 19, 2026
Merged

docs: OPENSSL_CONF workaround for TLS handshake on OpenSSL 3.5+#752
gijzelaerr merged 1 commit into
gijzelaerr:masterfrom
gridsociety:s7commplus-tls-openssl-doc

Conversation

@ale-rinaldi

Copy link
Copy Markdown
Contributor

Document the OPENSSL_CONF workaround for TLS on OpenSSL 3.5+

Follow-up to #746. That PR restricted the TLS 1.3 key-exchange groups in-code via ctypes, which was (rightly) declined now that the ctypes dependency is gone. This documents the pure-configuration alternative instead.

Background

On OpenSSL ≥ 3.5 (Debian 13, recent distros) the default TLS 1.3 ClientHello advertises the post-quantum hybrid group X25519MLKEM768, whose ~1.2 KB key share the S7-1500 rejects — it resets the connection mid-handshake, so connect(use_tls=True) fails.

I confirmed against a live S7-1500 that:

  • the PLC mandates TLS 1.3 — forcing TLS 1.2 is reset outright, so capping the version is not an option;
  • CPython's ssl exposes no API for the TLS 1.3 supported_groups list (set_ecdh_curve only affects ≤ TLS 1.2).

So the only dependency-free fix is to restrict the groups through OpenSSL's own config via OPENSSL_CONF.

What's here

A new subsection in doc/connecting.rst (under S7CommPlus over TLS) with the ready-to-use OPENSSL_CONF file, the Groups = x25519:secp256r1:secp384r1 setting, and a note that it must be set in the environment before the process starts (OpenSSL reads it once at init). Docs-only change.

On OpenSSL >= 3.5 the default TLS 1.3 ClientHello advertises the
X25519MLKEM768 post-quantum group, whose ~1.2 KB key share the S7-1500
rejects — it drops the handshake, so connect(use_tls=True) fails with a
connection reset. The PLC mandates TLS 1.3 (TLS 1.2 is refused outright)
and CPython's ssl exposes no API for the TLS 1.3 supported_groups list, so
document restricting them to classic ECDHE curves via an OPENSSL_CONF file.

Follow-up to gijzelaerr#746 (the in-code ctypes group restriction was declined).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@gijzelaerr gijzelaerr left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

Review

Docs-only, accurate, and well-written.

Correctness: The X25519MLKEM768 post-quantum group issue on OpenSSL ≥ 3.5 is a real problem — the ~1.2 KB key share exceeds what the S7-1500 TLS stack accepts. The OPENSSL_CONF approach is the correct workaround given CPython's ssl has no supported_groups API for TLS 1.3. The Groups = x25519:secp256r1:secp384r1 selection is sensible — standard ECDHE curves, no security downgrade.

Security: No concerns. These are the same curves OpenSSL < 3.5 used by default. Removing only the PQ hybrid group.

Placement: Fits naturally under the existing S7CommPlus TLS section in doc/connecting.rst.

Ready to merge.

@gijzelaerr gijzelaerr enabled auto-merge (squash) June 19, 2026 15:37
@gijzelaerr gijzelaerr disabled auto-merge June 19, 2026 15:39
@gijzelaerr gijzelaerr merged commit dfe97c8 into gijzelaerr:master Jun 19, 2026
36 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants