JDK-8162787 : Documentation the customization of the default enabled cipher suites via system properties
  • Type: Sub-task
  • Component: docs
  • Sub-Component: guides
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2016-07-29
  • Updated: 2018-03-01
  • Resolved: 2018-03-01
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 10
10Fixed
Description
jdk.tls.client.cipherSuites:
----------------------------
This system property contains a comma-separated list of supported cipher suite names specifying the client side default enabled cipher suites.  All other supported cipher suites are disabled for this default setting.  Unrecognized or unsupported cipher suite names specified in the property are ignored.  Explicit setting of enabled cipher suites will override this system property.
 
 
jdk.tls.server.cipherSuites:
----------------------------
This system property contains a comma-separated list of supported cipher suite names specifying the server side default enabled cipher suites. This has the same syntax and behavior as the jdk.tls.client.cipherSuites system property.
 
Please refer to "Java Cryptography Architecture Standard Algorithm Name Documentation" for the standard JSSE cipher suite names, and "Java Cryptography Architecture Oracle Providers Documentation" for the cipher suite names supported by the SunJSSE provider.
 
 
Applications can explicitly set the enabled cipher suites with:
1. SSLSocket.setEnabledCipherSuites(String[])
2. SSLEngine.setEnabledCipherSuites(String[])
3. SSLServerSocket.setEnabledCipherSuites(String[])
4. SSLParameters(String[] cipherSuites)
5. SSLParameters(String[] cipherSuites, String[] protocols)
6. SSLParameters.setCipherSuites(String[])
7. "https.cipherSuites" system property for HttpsURLConnection
 
 
The system properties, "jdk.tls.client.cipherSuites" and "jdk.tls.server.cipherSuites", define the customized default enabled cipher suites for client side and server side accordingly.
 
Each JSSE provider has its own provider default enabled cipher suites too.
 
There are three enabled cipher suites mechanisms in total.  The order of preference is (favorite choice first):
1. explicit setting
2. customized default
3. provider default
 
Explicit setting overrides the customized default and the provider default enabled cipher suites.  The customized default overrides the provider default enabled cipher suites.
 
Note that the actually use of enabled cipher suites is restricted by algorithm constraints.
 
Note that this system property is currently supported by the JDK Reference implementation. It is not guaranteed to be supported by other implementations.

Warning: the system property can be used to configure weak cipher suites, or the configured cipher suites may be weak in the future. We do not recommend to use the system property unless you know what you're doing. Use it at your own risk.