Package com.unboundid.util.ssl
Class TLSCipherSuiteSelector
- java.lang.Object
-
- com.unboundid.util.CommandLineTool
-
- com.unboundid.util.ssl.TLSCipherSuiteSelector
-
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class TLSCipherSuiteSelector extends CommandLineTool
This class provides a utility for selecting the cipher suites that should be supported for TLS communication. The logic used to select the recommended TLS cipher suites is as follows:-
In most JVMs, only cipher suites that use the TLS protocol will be
recommended (that is, suites that use a prefix of "TLS_"), and legacy SSL
suites (those that use a prefix of "SSL_") will not be recommended, nor
will any suites that use an unrecognized protocol. Note that this
restriction will not be enforced for JVMs in which the vendor string
contains "IBM" (as they tend to use "SSL_" prefixes for most or all
cipher suites), or if the
PROPERTY_ALLOW_SSL_PREFIX
system property is set totrue
. - Any cipher suite that uses a NULL key exchange, authentication, bulk encryption, or digest algorithm will not be recommended.
- Any cipher suite that uses anonymous authentication will not be recommended.
- Any cipher suite that uses weakened export-grade encryption will not be recommended.
- By default, only cipher suites that use the ECDHE or DHE key exchange algorithms will be recommended, as they allow for forward secrecy. Suites that use RSA key exchange algorithms (which don't support forward secrecy) will only be recommended if the JVM doesn't support either TLSv1.3 or TLSv1.2, or if overridden programmatically or by system property. Other key agreement algorithms (like ECDH, DH, and KRB5) will not be recommended. Similarly, cipher suites that use a pre-shared key or password will not be recommended.
- Only cipher suites that use AES or ChaCha20 bulk encryption ciphers will be recommended. Other bulk cipher algorithms (like RC4, DES, 3DES, IDEA, Camellia, and ARIA) will not be recommended.
- By default, only cipher suites that use SHA-2 digests will be recommended. SHA-1 suites will only be recommended if the JVM doesn't support either TLSv1.3 or TLSv1.2, or if overridden programmatically or by system property. All other digest algorithms (like MD5) will not be recommended.
Also note that this class can be used as a command-line tool for debugging purposes. -
In most JVMs, only cipher suites that use the TLS protocol will be
recommended (that is, suites that use a prefix of "TLS_"), and legacy SSL
suites (those that use a prefix of "SSL_") will not be recommended, nor
will any suites that use an unrecognized protocol. Note that this
restriction will not be enforced for JVMs in which the vendor string
contains "IBM" (as they tend to use "SSL_" prefixes for most or all
cipher suites), or if the
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
PROPERTY_ALLOW_RSA_KEY_EXCHANGE
The name of a system property (com.unboundid.util.ssl.TLSCipherSuiteSelector.allowRSAKeyExchange) that can be used to indicate whether to recommend cipher suites that use the RSA key exchange algorithm.static java.lang.String
PROPERTY_ALLOW_SHA_1
The name of a system property (com.unboundid.util.ssl.TLSCipherSuiteSelector.allowSHA1) that can be used to indicate whether to recommend cipher suites that use the SHA-1 digest algorithm.static java.lang.String
PROPERTY_ALLOW_SSL_PREFIX
The name of a system property (com.unboundid.util.ssl.TLSCipherSuiteSelector.allowSSLPrefix) that can be used to indicate whether to recommend cipher suites that use a prefix of "SSL_" rather than "TLS_".
-
Constructor Summary
Constructors Constructor Description TLSCipherSuiteSelector(java.io.OutputStream out, java.io.OutputStream err)
Creates a new instance of this TLS cipher suite selector that will use the provided output streams.TLSCipherSuiteSelector(java.io.OutputStream out, java.io.OutputStream err, boolean useJVMDefaults)
Creates a new instance of this TLS cipher suite selector that will use the provided output streams.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addToolArguments(ArgumentParser parser)
Adds the command-line arguments supported for use with this tool to the provided argument parser.static boolean
allowRSAKeyExchange()
Indicates whether cipher suites that use the RSA key exchange algorithm should be recommended by default.static boolean
allowSHA1()
Indicates whether cipher suites that use the SHA-1 digest algorithm should be recommended by default.static boolean
allowSSLPrefixedSuites()
Indicates whether cipher suites whose names start with "SSL_" should be recommended by default.ResultCode
doToolProcessing()
Performs the core set of processing for this tool.static java.util.SortedSet<java.lang.String>
getDefaultCipherSuites()
Retrieves the set of TLS cipher suites enabled by default in the JVM.static java.util.SortedMap<java.lang.String,java.util.List<java.lang.String>>
getNonRecommendedCipherSuites()
Retrieves a map containing the TLS cipher suites that are supported by the JVM but are not recommended for use.static java.lang.String[]
getRecommendedCipherSuiteArray()
Retrieves an array containing the recommended set of TLS cipher suites as selected by this class.static java.util.SortedSet<java.lang.String>
getRecommendedCipherSuites()
Retrieves the recommended set of TLS cipher suites as selected by this class.static java.util.SortedSet<java.lang.String>
getSupportedCipherSuites()
Retrieves the set of all TLS cipher suites supported by the JVM.java.lang.String
getToolDescription()
Retrieves a human-readable description for this tool.java.lang.String
getToolName()
Retrieves the name of this tool.java.lang.String
getToolVersion()
Retrieves a version string for this tool, if available.static ResultCode
main(java.io.OutputStream out, java.io.OutputStream err, java.lang.String... args)
Invokes this command-line program with the provided set of arguments.static void
main(java.lang.String... args)
Invokes this command-line program with the provided set of arguments.static void
recompute()
Re-computes the default instance of this cipher suite selector.static java.util.Set<java.lang.String>
selectSupportedCipherSuites(java.util.Collection<java.lang.String> potentialSuiteNames)
Filters the provided collection of potential cipher suite names to retrieve a set of the suites that are supported by the JVM.static void
setAllowRSAKeyExchange(boolean allowRSAKeyExchange)
Specifies whether cipher suites that use the RSA key exchange algorithm should be recommended by default.static void
setAllowSHA1(boolean allowSHA1)
Specifies whether cipher suites that use the SHA-1 digest algorithm should be recommended by default.static void
setAllowSSLPrefixedSuites(boolean allowSSLPrefix)
Specifies whether cipher suites whose names start with "SSL_" should be recommended by default.-
Methods inherited from class com.unboundid.util.CommandLineTool
addEnableSSLDebuggingArgument, createArgumentParser, defaultsToInteractiveMode, doExtendedArgumentValidation, doShutdownHookProcessing, err, getAdditionalDescriptionParagraphs, getErr, getExampleUsages, getMaxTrailingArguments, getMinTrailingArguments, getOriginalErr, getOriginalOut, getOut, getPasswordFileReader, getToolCompletionMessage, getTrailingArgumentsPlaceholder, logToolInvocationByDefault, out, registerShutdownHook, requestToolArgumentsInteractively, runTool, supportsInteractiveMode, supportsOutputFile, supportsPropertiesFile, wrapErr, wrapOut
-
-
-
-
Field Detail
-
PROPERTY_ALLOW_RSA_KEY_EXCHANGE
@NotNull public static final java.lang.String PROPERTY_ALLOW_RSA_KEY_EXCHANGE
The name of a system property (com.unboundid.util.ssl.TLSCipherSuiteSelector.allowRSAKeyExchange) that can be used to indicate whether to recommend cipher suites that use the RSA key exchange algorithm. RSA key exchange does not support forward secrecy, so it will not be recommended by default unless the JVM doesn't support either TLSv1.3 or TLSv1.2. This can be overridden via thesetAllowRSAKeyExchange(boolean)
method.
-
PROPERTY_ALLOW_SHA_1
@NotNull public static final java.lang.String PROPERTY_ALLOW_SHA_1
The name of a system property (com.unboundid.util.ssl.TLSCipherSuiteSelector.allowSHA1) that can be used to indicate whether to recommend cipher suites that use the SHA-1 digest algorithm. The SHA-1 digest is now considered weak, so it will not be recommended by default unless the JVM doesn't support either TLSv1.3 or TLSv1.2. This can be overridden via thesetAllowSHA1(boolean)
method.
-
PROPERTY_ALLOW_SSL_PREFIX
@NotNull public static final java.lang.String PROPERTY_ALLOW_SSL_PREFIX
The name of a system property (com.unboundid.util.ssl.TLSCipherSuiteSelector.allowSSLPrefix) that can be used to indicate whether to recommend cipher suites that use a prefix of "SSL_" rather than "TLS_". If this is not specified, then the default behavior will be to disable all suites with an "SSL_" prefix for all non-IBM JVMs, but to allow them for JVMs in which the vendor string contains "IBM", as they are known to use "SSL_" prefixes even for suites that are only in use in conjunction with TLS protocols.
-
-
Constructor Detail
-
TLSCipherSuiteSelector
public TLSCipherSuiteSelector(@Nullable java.io.OutputStream out, @Nullable java.io.OutputStream err)
Creates a new instance of this TLS cipher suite selector that will use the provided output streams. Note that this constructor should only be used when invoking it as a command-line tool.- Parameters:
out
- The output stream to use for standard output. It may benull
if standard output should be suppressed.err
- The output stream to use for standard error. It may benull
if standard error should be suppressed.
-
TLSCipherSuiteSelector
public TLSCipherSuiteSelector(@Nullable java.io.OutputStream out, @Nullable java.io.OutputStream err, boolean useJVMDefaults)
Creates a new instance of this TLS cipher suite selector that will use the provided output streams. Note that this constructor should only be used when invoking it as a command-line tool.- Parameters:
out
- The output stream to use for standard output. It may benull
if standard output should be suppressed.err
- The output stream to use for standard error. It may benull
if standard error should be suppressed.useJVMDefaults
- Indicates whether to use the JVM-default settings. This should only betrue
for the initial instance created before the static initializer has run.
-
-
Method Detail
-
main
public static void main(@NotNull java.lang.String... args)
Invokes this command-line program with the provided set of arguments.- Parameters:
args
- The command-line arguments provided to this program.
-
main
@NotNull public static ResultCode main(@Nullable java.io.OutputStream out, @Nullable java.io.OutputStream err, @NotNull java.lang.String... args)
Invokes this command-line program with the provided set of arguments.- Parameters:
out
- The output stream to use for standard output. It may benull
if standard output should be suppressed.err
- The output stream to use for standard error. It may benull
if standard error should be suppressed.args
- The command-line arguments provided to this program.- Returns:
- A result code that indicates whether the processing was successful.
-
getSupportedCipherSuites
@NotNull public static java.util.SortedSet<java.lang.String> getSupportedCipherSuites()
Retrieves the set of all TLS cipher suites supported by the JVM. The set will be sorted in order of most preferred to least preferred, as determined by theTLSCipherSuiteComparator
.- Returns:
- The set of all TLS cipher suites supported by the JVM.
-
getDefaultCipherSuites
@NotNull public static java.util.SortedSet<java.lang.String> getDefaultCipherSuites()
Retrieves the set of TLS cipher suites enabled by default in the JVM. The set will be sorted in order of most preferred to least preferred, as determined by theTLSCipherSuiteComparator
.- Returns:
- The set of TLS cipher suites enabled by default in the JVM.
-
getRecommendedCipherSuites
@NotNull public static java.util.SortedSet<java.lang.String> getRecommendedCipherSuites()
Retrieves the recommended set of TLS cipher suites as selected by this class. The set will be sorted in order of most preferred to least preferred, as determined by theTLSCipherSuiteComparator
.- Returns:
- The recommended set of TLS cipher suites as selected by this class.
-
getRecommendedCipherSuiteArray
@NotNull public static java.lang.String[] getRecommendedCipherSuiteArray()
Retrieves an array containing the recommended set of TLS cipher suites as selected by this class. The array will be sorted in order of most preferred to least preferred, as determined by theTLSCipherSuiteComparator
.- Returns:
- An array containing the recommended set of TLS cipher suites as selected by this class.
-
getNonRecommendedCipherSuites
@NotNull public static java.util.SortedMap<java.lang.String,java.util.List<java.lang.String>> getNonRecommendedCipherSuites()
Retrieves a map containing the TLS cipher suites that are supported by the JVM but are not recommended for use. The keys of the map will be the names of the non-recommended cipher suites, sorted in order of most preferred to least preferred, as determined by theTLSCipherSuiteComparator
. Each TLS cipher suite name will be mapped to a list of the reasons it is not recommended for use.- Returns:
- A map containing the TLS cipher suites that are supported by the JVM but are not recommended for use
-
getToolName
@NotNull public java.lang.String getToolName()
Retrieves the name of this tool. It should be the name of the command used to invoke this tool.- Specified by:
getToolName
in classCommandLineTool
- Returns:
- The name for this tool.
-
getToolDescription
@NotNull public java.lang.String getToolDescription()
Retrieves a human-readable description for this tool. If the description should include multiple paragraphs, then this method should return the text for the first paragraph, and theCommandLineTool.getAdditionalDescriptionParagraphs()
method should be used to return the text for the subsequent paragraphs.- Specified by:
getToolDescription
in classCommandLineTool
- Returns:
- A human-readable description for this tool.
-
getToolVersion
@NotNull public java.lang.String getToolVersion()
Retrieves a version string for this tool, if available.- Overrides:
getToolVersion
in classCommandLineTool
- Returns:
- A version string for this tool, or
null
if none is available.
-
addToolArguments
public void addToolArguments(@NotNull ArgumentParser parser) throws ArgumentException
Adds the command-line arguments supported for use with this tool to the provided argument parser. The tool may need to retain references to the arguments (and/or the argument parser, if trailing arguments are allowed) to it in order to obtain their values for use in later processing.- Specified by:
addToolArguments
in classCommandLineTool
- Parameters:
parser
- The argument parser to which the arguments are to be added.- Throws:
ArgumentException
- If a problem occurs while adding any of the tool-specific arguments to the provided argument parser.
-
doToolProcessing
@NotNull public ResultCode doToolProcessing()
Performs the core set of processing for this tool.- Specified by:
doToolProcessing
in classCommandLineTool
- Returns:
- A result code that indicates whether the processing completed successfully.
-
selectSupportedCipherSuites
@NotNull public static java.util.Set<java.lang.String> selectSupportedCipherSuites(@Nullable java.util.Collection<java.lang.String> potentialSuiteNames)
Filters the provided collection of potential cipher suite names to retrieve a set of the suites that are supported by the JVM.- Parameters:
potentialSuiteNames
- The collection of cipher suite names to be filtered.- Returns:
- The set of provided cipher suites that are supported by the JVM, or an empty set if none of the potential provided suite names are supported by the JVM.
-
allowRSAKeyExchange
public static boolean allowRSAKeyExchange()
Indicates whether cipher suites that use the RSA key exchange algorithm should be recommended by default.- Returns:
true
if cipher suites that use the RSA key exchange algorithm should be recommended by default, orfalse
if not.
-
setAllowRSAKeyExchange
public static void setAllowRSAKeyExchange(boolean allowRSAKeyExchange)
Specifies whether cipher suites that use the RSA key exchange algorithm should be recommended by default.- Parameters:
allowRSAKeyExchange
- Indicates whether cipher suites that use the RSA key exchange algorithm should be recommended by default.
-
allowSHA1
public static boolean allowSHA1()
Indicates whether cipher suites that use the SHA-1 digest algorithm should be recommended by default.- Returns:
true
if cipher suites that use the SHA-1 digest algorithm should be recommended by default, orfalse
if not.
-
setAllowSHA1
public static void setAllowSHA1(boolean allowSHA1)
Specifies whether cipher suites that use the SHA-1 digest algorithm should be recommended by default.- Parameters:
allowSHA1
- Indicates whether cipher suites that use the SHA-1 digest algorithm should be recommended by default.
-
allowSSLPrefixedSuites
public static boolean allowSSLPrefixedSuites()
Indicates whether cipher suites whose names start with "SSL_" should be recommended by default.- Returns:
true
if cipher suites prefixed with either "SSL_" or "TLS_" should be recommended by default, orfalse
if only suites prefixed with "TLS_" should be recommended by default.
-
setAllowSSLPrefixedSuites
public static void setAllowSSLPrefixedSuites(boolean allowSSLPrefix)
Specifies whether cipher suites whose names start with "SSL_" should be recommended by default.- Parameters:
allowSSLPrefix
- Indicates whether cipher suites whose names start with "SSL_" should be recommended by default. If this istrue
, then suites prefixed with either "TLS_" or "SSL_" may be recommended. If this isfalse
, then only suites prefixed with "TLS_" may be recommended.
-
recompute
public static void recompute()
Re-computes the default instance of this cipher suite selector. This may be necessary after certain actions that alter the supported set of TLS cipher suites (for example, installing or removing cryptographic providers).
-
-