WL#17311: Support Post-Quantum Cryptography for OpenSSL >= 3.5

OpenSSL 3.5 introduces post-quantum cryptography (PQC) algorithms for TLS 1.3 key exchange and handshake signing. MySQL Server, libmysqlclient, and libmysqlxclient provide support for these algorithms.

MySQL Shell uses these client libraries for Classic Protocol and X Protocol connections. Shell must expose the new client-library options through its existing connection interfaces and allow users to inspect the algorithms negotiated for an established session.

Users can configure MySQL Shell connections with:

• tls-kex, to select the permitted TLS key-exchange groups;
• force-pqc, to request enforcement of a PQC-capable key exchange by the client library;
• use-pqc-sign, to allow the client library to advertise PQC-capable TLS handshake signature algorithms.

The options are available for both Classic Protocol and X Protocol connections through:

• MySQL Shell command-line options;
• URI connection options;
• dictionary connection options.

MySQL Shell also reports the negotiated TLS key-exchange and handshake-signature algorithms through \status and shell.status() when the connected server exposes this information.

This WorkLog covers representing, accepting, preserving, overriding, serializing, and forwarding the three connection options; documenting them in Shell help; reporting the negotiated algorithms; and testing the Shell-owned behavior for both protocols.

Functional Requirements

FR1 - MySQL Shell must expose tls-kex, force-pqc, and use-pqc-sign for Classic Protocol and X Protocol connections.

FR2 - The options must be accepted through the MySQL Shell command line, URI connection data, and dictionary connection data.

FR3 - tls-kex must be a string option that requires a value when specified. MySQL Shell must preserve its value and case when passing it to the selected client library. When the option is not specified, Shell must leave the client-library setting unset.

FR4 - force-pqc must be a Boolean option with a default of false.

FR5 - use-pqc-sign must be a Boolean option with a default of false.

FR6 - MySQL Shell must pass the effective values of the three options to the client library used by the selected protocol before establishing the connection.

FR7 - \status and shell.status() must display the negotiated TLS key-exchange and handshake-signature algorithms when the connected server exposes the corresponding session status variables.

Non-Functional Requirements

NFR1 - Existing connections that do not specify the new options must retain their current behavior.

NFR2 - Option names, types, defaults, and behavior must be consistent between Classic Protocol and X Protocol, except for documented client-library limitations.

NFR3 - Cryptographic capability detection, algorithm validation, TLS negotiation, PQC enforcement, and session-resumption behavior remain the responsibility of libmysqlclient and libmysqlxclient.

NFR4 - Tests must verify Shell-owned behavior: parsing, precedence, serialization, forwarding, error propagation, and status presentation for both protocols.

Connection Options

The options are available to Shell commands and APIs that accept the standard connection-data URI or dictionary.

Command-Line Interface

The new command-line interfaces are:

--tls-kex=<group-list>
--force-pqc[=<bool>]
--use-pqc-sign[=<bool>]

They may be used with either --mysql or --mysqlx.

Example:

mysqlsh --mysql \
  --uri user@host:3306 \
  --ssl-mode=REQUIRED \
  --tls-version=TLSv1.3 \
  --force-pqc \
  --tls-kex=X25519MLKEM768:secp384r1MLKEM1024

URI Interface

The options may be supplied as URI query attributes.

Classic Protocol example:

mysql://user@host:3306?ssl-mode=REQUIRED&tls-version=TLSv1.3&force-pqc=true&tls-kex=X25519MLKEM768

X Protocol example:

mysqlx://user@host:33060?ssl-mode=REQUIRED&tls-version=TLSv1.3&force-pqc=true

URI values follow the existing MySQL Shell URL-encoding rules.

Dictionary Interface

JavaScript example:

shell.connect({
    scheme: "mysql",
    user: "user",
    host: "host",
    port: 3306,
    "ssl-mode": "REQUIRED",
    "tls-version": "TLSv1.3",
    "force-pqc": true,
    "tls-kex": "X25519MLKEM768",
    "use-pqc-sign": true
})

Python example:

shell.connect({
    "scheme": "mysqlx",
    "user": "user",
    "host": "host",
    "port": 33060,
    "ssl-mode": "REQUIRED",
    "tls-version": "TLSv1.3",
    "force-pqc": True,
    "tls-kex": "X25519MLKEM768",
    "use-pqc-sign": True
})

Option Semantics

tls-kex

tls-kex specifies a colon-separated list of TLS key-exchange group names that is passed unchanged to the selected client library. The option requires a value when specified. When the option is not specified, Shell does not set the corresponding client-library option and the client library uses its default.

The algorithm names are case-sensitive. The client library used for the connection determines the supported names and how invalid or unsupported values are handled. MySQL Shell does not maintain or validate the list.

force-pqc

force-pqc passes the requested Boolean value to the selected client library. The client library determines whether a PQC-capable key exchange can be used and whether connection establishment must fail.

This option does not replace the existing ssl-mode or tls-version options. Users who require an encrypted TLS 1.3 connection must configure those options accordingly.

use-pqc-sign

use-pqc-sign passes the requested Boolean value to the selected client library. The client library controls advertisement and selection of TLS handshake signature algorithms. Enabling the option does not guarantee that a PQC signature algorithm is selected.

Status Output

When the connected server exposes the Tls_key_exchange_algorithm and Tls_sign_algorithm session status variables, \status and shell.status() display equivalent fields:

TLS key exchange algorithm: X25519MLKEM768
TLS signature algorithm: rsa_pss_rsae_sha256

The values identify the algorithms reported for the established session; they do not echo the requested connection options.

When connected to a server that does not define the corresponding status variables, Shell omits these fields without causing the status operation to fail. When a variable exists but contains an empty value, Shell preserves that value.

Connection Option Representation

The three options are added to mysqlshdk::db::Ssl_options so they participate in the existing SSL option handling.

• tls-kex is stored as a nullable string. When it is not specified, its unset state is preserved and no client-library option is set.
• force-pqc and use-pqc-sign have typed Boolean accessors and an effective default of false.
• Boolean values supplied through a URI, dictionary, or command-line option use the existing Shell Boolean conversion and validation.

The connection-option attribute sets are extended so that the options are accepted in URIs and dictionaries and included in URI serialization. The existing connection-option override and SSL-option clearing paths are extended to include the three options.

Dictionary processing must accept native Boolean values for force-pqc and use-pqc-sign. tls-kex must be processed as a string.

Command-Line Option Handling

mysqlshdk::shellcore::Shell_options registers:

--tls-kex=<group-list>
--force-pqc[=<bool>]
--use-pqc-sign[=<bool>]

tls-kex uses the existing value-required option handling. The Boolean options use the existing Shell Boolean-option handling, including its enable, disable, and skip forms.

The option handlers store their values in the same Ssl_options instance used by URI and dictionary connection data. Existing connection-option precedence then determines the effective value.

Client-Library Mapping

For Classic Protocol connections, Shell passes the option values using:

• MYSQL_OPT_TLS_KEX;
• MYSQL_OPT_FORCE_PQC;
• MYSQL_OPT_USE_PQC_SIGN.

For X Protocol connections, Shell passes the option values using the corresponding libmysqlxclient session options.

The client libraries remain responsible for OpenSSL-version checks, supported algorithm names, TLS negotiation, PQC enforcement, signature selection, and session-resumption behavior. Client-library connection errors are reported through Shell's existing connection-error handling.

The Classic Protocol setup sets MYSQL_OPT_TLS_KEX only when tls-kex has been specified. The X Protocol setup follows the same unset behavior.

The effective Boolean defaults must be consistent across the two protocols. If an underlying client library uses a different internal default, Shell must set the corresponding option explicitly or the client-library dependency must be corrected before integration.

Status Collection

The Classic Protocol and X Protocol session status implementations query:

SHOW SESSION STATUS LIKE 'Tls_key_exchange_algorithm'
SHOW SESSION STATUS LIKE 'Tls_sign_algorithm'

When a query returns a row, its value is added to the session status data used by \status and shell.status(). When no row is returned, no field is added. This preserves compatibility with servers that do not expose the corresponding status variable.

An empty value returned by the server is stored without interpretation. Shell does not infer whether the connection used PQC from an algorithm name.

Error Handling

Shell performs only its existing connection-option type validation. It does not validate the contents of tls-kex or add PQC-specific connection error handling.

Errors reported by the client library during connection establishment use the existing Classic Protocol or X Protocol error path.