Documentation, Remove the weaker ciphers from the Strong list in the Cipher suite settings for SSL and Update the Ephemeral DH Key Size

[rangaran]

Feature epic details

• For the title of this issue, type: Documentation, Development epic name
• Link to development epic: https://github.ibm.com/websphere/WS-CD-Open/issues/28213
• Target GA release: TBA, feature is under development

Operating systems

Does the documentation apply to all operating systems?

• Yes
• No; specify operating systems: ______

Summary

Provide a concise summary of your feature. What is the update, why does it matter, and to whom? What do 80% of target users need to know to be most easily productive using your runtime update?

This update strengthens Liberty’s default cryptographic configuration by removing support for ciphers that use RSA key exchange and non-ephemeral ECDH. In addition, the ephemeral Diffie-Hellman key size is standardized at 2048 bits through the jdk.tls.ephemeralDHKeySize setting, aligning with current security best practices.

Liberty will also no longer rely on the legacy HIGH/MEDIUM/LOW cipher categories. Instead, it will use a default cipher list derived from the JDK’s supported ciphers and filtered using the same criteria previously applied to HIGH, with the added exclusion of RSA key-exchange ciphers. Users may continue to supply a custom cipher list if different behaviour is required.

For most users, no action is needed: Liberty will automatically apply more secure defaults. Users with compatibility requirements for older clients should review these changes and configure a custom cipher list if necessary.

Configuration

List any new or changed properties, parameters, elements, attributes, etc. Include default values and configuration examples where relevant:

Removed Attributes:

• securityLevel (ssl configuration element)

Previously supported values:

• HIGH (default), MEDIUM, LOW, CUSTOM

Change:

• The securityLevel attribute is no longer supported and is ignored if specified.
• Cipher selection is now using a default list or custom list specified by enabledCiphers.

Previous configuration (no longer applicable):

<ssl id="defaultSSL" securityLevel="HIGH"/>
<ssl id="defaultSSL" securityLevel="CUSTOM"
     enabledCiphers="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ..."/>

Updated configuration:

<ssl id="defaultSSL"/>
<ssl id="defaultSSL"
     enabledCiphers="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ..."/>

Modified Behavior

Default Cipher Selection:

• When enabledCiphers is not specified or empty:

  • Liberty uses a default cipher list derived from the JDK’s supported ciphers.
  • The default list excludes:
    - Ciphers using RSA key exchange
    - Ciphers using non-ephemeral ECDH key exchange

• When enabledCiphers is specified:

  • Liberty uses only the explicitly configured cipher list.

New / Enforced System Property

-Djdk.tls.ephemeralDHKeySize=2048

• Type: JVM system property

• Scope: JVM-wide

• Default value: 2048 (set by Liberty if not explicitly configured)

• Description: Specifies the key size used for ephemeral Diffie-Hellman keys.

System Property Behavior:

• Property not set

  • Liberty sets the value to 2048 with a debug log

• Property set to 2048

  • Value is used as configured

• Property set to a value greater than 2048

  • Value is used as configured

• Property set to a value lower than 2048

  • Value is used as configured with a warning

Updates to existing topics

To update existing topics, specify a link to the topics that are affected. Include a copy of the current text and the exact text to which it will change. For example: Change ABC to XYZ

• enableCiphers: Used without the securityLevel, CUSTOM
• securityLevel: Removed
• jdk.tls.ephemeralDHKeySize: Set default value as specified in the System Property Behaviour section of this doc

Create a new topic

To create a topic, specify a first draft of the topic that you want added and the section in the navigation where the topic should go.