Technical Analysis: Clarifying ssl_groups Parameter Documentation for Post-Quantum Key Exchange

Core Problem

PostgreSQL 18 introduced the ssl_groups GUC parameter to replace the older ssl_ecdh_curve parameter, reflecting OpenSSL's evolution from supporting only elliptic curve Diffie-Hellman (ECDH) groups to a broader set of named groups for TLS key exchange. However, the documentation and internal naming still describe this parameter narrowly as being for "Diffie-Hellman key exchange" and references "curves," which is technically inaccurate given the parameter's actual capabilities.

The fundamental issue is that ssl_groups is a thin wrapper around OpenSSL's SSL_CTX_set1_groups_list(), which accepts any named group supported by the underlying cryptographic library. Since OpenSSL 3.5, this includes post-quantum/quantum-resistant key encapsulation mechanisms (KEMs) like MLKEM768 (Module-Lattice-Based Key-Encapsulation Mechanism, standardized by NIST). These are not Diffie-Hellman key exchanges — they are lattice-based KEMs designed to be resistant to Shor's algorithm (which would break traditional DH and ECDH on a sufficiently powerful quantum computer).

Architectural Significance

This matters for several reasons:

1. Correctness of documentation: Users configuring PostgreSQL for post-quantum TLS security need to understand that ssl_groups supports more than just DH groups. The current description actively misleads administrators into thinking only DH-family groups are valid.

2. Future-proofing: As post-quantum cryptography adoption accelerates (NIST finalized ML-KEM in 2024), PostgreSQL's TLS configuration needs to accurately reflect what the underlying OpenSSL API supports without requiring code changes for each new algorithm family.

3. Security posture: Organizations preparing for "harvest now, decrypt later" quantum threats need clarity that PostgreSQL can be configured with quantum-safe key exchange mechanisms when the OpenSSL version supports them.

Proposed Solution

The patch makes documentation and naming changes (no behavioral changes):

1. GUC short_desc update: Changes from "Sets the group(s) to use for Diffie-Hellman key exchange" to something like "Sets the named groups to use for TLS key exchange" — removing the DH-specific language.

2. Documentation update: The runtime config documentation for ssl_groups is updated to remove references to "curves" and "Diffie-Hellman" in favor of generic "named groups" / "key exchange" terminology.

3. Internal function rename (v2): The internal initialization function is renamed (likely from something like initialize_ecdh() to initialize_groups()) to reflect the broader scope.

4. Comment updates (v2): Stale comments referencing "ephemeral DH and ECDH keys" and "ECDH curve" are updated throughout be-secure.c and related files.

5. Variable rename (v2): The SSLECDHCurve extern variable is renamed for consistency, since no external usage was found in the wild.

Key Design Decisions and Tradeoffs

• No behavioral change: The patch is purely cosmetic/documentary. The parameter already works with post-quantum groups if the OpenSSL version supports them — this just makes that fact visible to users.

• Scope expansion in v2: The initial patch was conservative (just the GUC description and docs). After review feedback, v2 expanded to rename internal variables and update comments. This is a reasonable tradeoff — the v1 approach of minimal change reduces risk but leaves inconsistency; v2 is more thorough but touches more code.

• Extern variable rename: Renaming SSLECDHCurve is slightly more aggressive since it's technically a public symbol, but the author verified no external usage exists. This is the right call — leaving stale naming in externally-visible symbols creates long-term confusion.

Technical Context

The evolution of OpenSSL's group/curve API reflects a broader cryptographic transition:

• OpenSSL < 1.1: SSL_CTX_set_tmp_ecdh() with explicit curve objects
• OpenSSL 1.1+: SSL_CTX_set1_curves_list() (string-based, but still "curves")
• OpenSSL 3.0+: SSL_CTX_set1_groups_list() (renamed to "groups" to be algorithm-agnostic)
• OpenSSL 3.5+: Supports ML-KEM groups in the same API

PostgreSQL's ssl_groups parameter correctly tracks this API evolution at the functional level, but the documentation lagged behind.