org.wildfly.security.ssl

Class CipherSuiteSelector

java.lang.Object

org.wildfly.security.ssl.CipherSuiteSelector

public abstract class CipherSuiteSelector
extends Object

An immutable filter for SSL/TLS cipher suites.

Author:

David M. Lloyd

Method Summary

Modifier and Type	Method and Description
CipherSuiteSelector	add(CipherSuitePredicate predicate) Add all cipher suites which are matched by the given predicate.
CipherSuiteSelector	add(String cipherSuiteName) A convenience method to add a cipher suite by name.
CipherSuiteSelector	deleteFully(CipherSuitePredicate predicate) Permanently delete all cipher suites which are matched by the given predicate.
CipherSuiteSelector	deleteFully(String cipherSuiteName) A convenience method to permanently delete a cipher suite by name.
static CipherSuiteSelector	empty() Get the basic empty SSL cipher suite selector.
String[]	evaluate(String[] supportedMechanisms) Evaluate this selector against the given list of JSSE supported mechanisms.
static CipherSuiteSelector	fromString(String string) Create a cipher suite selector from the given OpenSSL-style cipher list string.
static CipherSuiteSelector	openSslAll() Get the cipher selector which OpenSSL defines as ALL.
static CipherSuiteSelector	openSslDefault() Get the cipher selector which OpenSSL defines as DEFAULT.
CipherSuiteSelector	pushToEnd(CipherSuitePredicate predicate) Push all cipher suites which are matched by the given predicate to the end of the enabled ciphers list.
CipherSuiteSelector	pushToEnd(String cipherSuiteName) A convenience method to push a cipher suite by name to the end of the enabled ciphers list.
CipherSuiteSelector	remove(CipherSuitePredicate predicate) Remove all cipher suites which are matched by the given predicate.
CipherSuiteSelector	remove(String cipherSuiteName) A convenience method to remove a cipher suite by name.
CipherSuiteSelector	sortByAlgorithmKeyLength() Sort all of the enabled ciphers by decreasing key length.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

empty

public static CipherSuiteSelector empty()

Get the basic empty SSL cipher suite selector.

Returns:

the empty selector

openSslDefault

public static CipherSuiteSelector openSslDefault()

Get the cipher selector which OpenSSL defines as DEFAULT.

Returns:

the selector

See Also:

CipherSuitePredicate.matchOpenSslDefaultDeletes()

openSslAll

public static CipherSuiteSelector openSslAll()

Get the cipher selector which OpenSSL defines as ALL.

Returns:

the selector

See Also:

CipherSuitePredicate.matchOpenSslAll()

deleteFully

public CipherSuiteSelector deleteFully(CipherSuitePredicate predicate)

Permanently delete all cipher suites which are matched by the given predicate. Matching ciphers cannot be re-added by a later rule (such rules will be ignored).

Parameters:

predicate - the predicate to match

Returns:

a new selector which includes the new rule

deleteFully

public CipherSuiteSelector deleteFully(String cipherSuiteName)

A convenience method to permanently delete a cipher suite by name. This is a shortcut for calling deleteFully(Predicate.matchName(cipherSuiteName)). The cipher suite name must be a standard or OpenSSL-style mechanism name identifying a single mechanism.

Parameters:

cipherSuiteName - the cipher suite name

Returns:

a new selector which includes the new rule

remove

public CipherSuiteSelector remove(CipherSuitePredicate predicate)

Remove all cipher suites which are matched by the given predicate. Matching ciphers may be re-added by a later rule.

Parameters:

predicate - the predicate to match

Returns:

a new selector which includes the new rule

remove

public CipherSuiteSelector remove(String cipherSuiteName)

A convenience method to remove a cipher suite by name. This is a shortcut for calling remove(Predicate.matchName(cipherSuiteName)). The cipher suite name must be a standard or OpenSSL-style mechanism name identifying a single mechanism.

Parameters:

cipherSuiteName - the cipher suite name

Returns:

a new selector which includes the new rule

add

public CipherSuiteSelector add(CipherSuitePredicate predicate)

Add all cipher suites which are matched by the given predicate. The cipher suites are added in a reasonably logical order. Any suites which are not supported by the underlying socket layer will not be added.

Parameters:

predicate - the predicate to match

Returns:

a new selector which includes the new rule

add

public CipherSuiteSelector add(String cipherSuiteName)

A convenience method to add a cipher suite by name. If the underlying socket layer does not support the named cipher suite, or if the cipher suite is invalid, it will not be added. This is a shortcut for calling add(Predicate.matchName(cipherSuiteName)). The cipher suite name must be a standard or OpenSSL-style mechanism name identifying a single mechanism.

Parameters:

cipherSuiteName - the cipher suite name

Returns:

a new selector which includes the new rule

pushToEnd

public CipherSuiteSelector pushToEnd(CipherSuitePredicate predicate)

Push all cipher suites which are matched by the given predicate to the end of the enabled ciphers list. Only cipher suites which are already enabled will be moved; no cipher suites are added by this transformation.

Parameters:

predicate - the predicate to match

Returns:

a new selector which includes the new rule

pushToEnd

public CipherSuiteSelector pushToEnd(String cipherSuiteName)

A convenience method to push a cipher suite by name to the end of the enabled ciphers list. This is a shortcut for calling pushToEnd(Predicate.matchName(cipherSuiteName)). In particular, no cipher suites are added by this transformation. The cipher suite name must be a standard or OpenSSL-style mechanism name identifying a single mechanism.

Parameters:

cipherSuiteName - the cipher suite name

Returns:

a new selector which includes the new rule

sortByAlgorithmKeyLength

public CipherSuiteSelector sortByAlgorithmKeyLength()

Sort all of the enabled ciphers by decreasing key length. Only the ciphers which were added by previous rules will be sorted.

Returns:

a new selector which includes the sort

toString

public final String toString()

Overrides:

toString in class Object

evaluate

public final String[] evaluate(String[] supportedMechanisms)

Evaluate this selector against the given list of JSSE supported mechanisms.

Parameters:

supportedMechanisms - the supported mechanisms

Returns:

the enabled mechanisms (not null)

fromString

public static CipherSuiteSelector fromString(String string)
                                      throws IllegalArgumentException

Create a cipher suite selector from the given OpenSSL-style cipher list string. The rules of the string are as follows:

• Each item is separated from the other items by a colon (":"), though for compatibility, commas (",") or spaces (" ") are allowed delimiters as well.
• The items are evaluated in order from left to right.
• Each item may consist of one of the following:
  • An OpenSSL-style cipher suite name like DH-RSA-AES256-SHA256, which adds the named cipher suite to the end of the list (if it is supported and not already present).
  • A standard SSL/TLS cipher suite name like TLS_DH_RSA_WITH_AES_256_CBC_SHA256, which adds the named cipher suite to the end of the list (if it is supported and not already present).
  • Any of the following special keywords:
    • HIGH, which matches all supported cipher suites with "high" encryption, presently defined as all cipher suites with key lengths larger than 128 bits, and some with key lengths of exactly 128 bits (see SecurityLevel.HIGH).
    • MEDIUM, which matches all supported cipher suites with "medium" encryption, presently defined as some cipher suites with 128 bit keys (see SecurityLevel.MEDIUM).
    • LOW, which matches all supported cipher suites with "low" encryption, presently defined as cipher suites which use 64- or 56-bit encryption but excluding export cipher suites (see SecurityLevel.LOW).
    • EXP or EXPORT, which matches supported cipher suites using export algorithms, presently defined as cipher suites which include those that use 56- or 40-bit encryption algorithms (see SecurityLevel.EXP40 and SecurityLevel.EXP56)
    .
    • EXPORT40, which matches supported cipher suites using export algorithms with 40-bit encryption (see SecurityLevel.EXP40).
    • EXPORT56, which matches supported cipher suites using export algorithms with 56-bit encryption (see SecurityLevel.EXP56).
    • eNULL or NULL, which matches supported cipher suites without encryption (see Encryption.NULL).
    • aNULL, which matches supported cipher suites without authentication (i.e. they are anonymous) (see Authentication.NULL).
    • kRSA, which matches supported cipher suites using RSA key exchange (see KeyAgreement.RSA).
    • aRSA, which matches supported cipher suites using RSA authentication (see Authentication.RSA).
    • RSA, which matches supported cipher suites using either RSA key exchange or RSA authentication.
    • kDHr, which matches supported cipher suites using DH key agreement with DH certificates signed with a RSA key (see KeyAgreement.DHr).
    • kDHd, which matches supported cipher suites using DH key agreement with DH certificates signed with a DSS key (see KeyAgreement.DHd).
    • kDH, which matches any supported cipher suite using DH key agreement.
    • kDHE or kEDH, which matches supported cipher suites using ephemeral DH key agreement (including anonymous cipher suites; see KeyAgreement.DHE).
    • DHE or EDH, which matches supported cipher suites using non-anonymous ephemeral DH key agreement.
    • ADH, which matches supported cipher suites using anonymous DH, not including anonymous elliptic curve suites.
    • DH, which matches any supported cipher suite using DH.
    • kECDHr, which matches supported cipher suites using fixed ECDH key agreement signed using RSA keys (see KeyAgreement.ECDHr).
    • kECDHe, which matches supported cipher suites using fixed ECDH key agreement signed by ECDSA keys (see KeyAgreement.ECDHe).
    • kECDH, which matches supported cipher suites using fixed ECDH key agreement.
    • kEECDH or kECDHE, which matches supported cipher suites using ephemeral ECDH key agreement (including anonymous cipher suites; see KeyAgreement.ECDHE).
    • ECDHE or EECDHE, which matches supported cipher suites using authenticated (non-anonymous) ephemeral ECDH key agreement.
    • AECDH, which matches supported cipher suites using anonymous ephemeral ECDH key agreement.
    • ECDH, which matches all supported cipher suites using ECDH key agreement.
    • aDSS or DSS, which matches supported cipher suites using DSS authentication (see Authentication.DSS).
    • aDH, which matches supported cipher suites using DH authentication (see Authentication.DH).
    • aECDH, which matches supported cipher suites using ECDH authentication (see Authentication.ECDH).
    • aECDSA or ECDSA, which matches supported cipher suites using ECDSA authentication (see Authentication.ECDSA).
    • kFZA, which matches supported cipher suites using Fortezza key agreement (see KeyAgreement.FZA).
    • aFZA, which matches supported cipher suites using Fortezza authentication (see Authentication.FZA).
    • eFZA, which matches supported cipher suites using Fortezza encryption (see Encryption.FZA).
    • FZA, which matches all supported cipher suites using any Fortezza algorithm.
    • TLSv1.2, which matches supported cipher suites defined in TLS v1.2 (see Protocol.TLSv1_2).
    • TLSv1, which matches supported cipher suites defined in TLS v1 (see Protocol.TLSv1).
    • SSLv3, which matches supported cipher suites defined in SSL v3.0 (see Protocol.SSLv3).
    • SSLv2, which matches supported cipher suites defined in SSL v2.0 (see Protocol.SSLv2).
    • AES256, which matches supported cipher suites using 256-bit AES (see Encryption.AES256).
    • AES128, which matches supported cipher suites using 128-bit AES (see Encryption.AES128).
    • AES, which matches all supported cipher suites using AES.
    • AESGCM, which matches supported cipher suites using AES in Galois Counter Mode (GCM) (see Encryption.AES256GCM and Encryption.AES128GCM).
    • CAMELLIA256, which matches supported cipher suites using 256-bit Camellia encryption (see Encryption.CAMELLIA256).
    • CAMELLIA128, which matches supported cipher suites using 128-bit Camellia encryption (see Encryption.CAMELLIA128).
    • CAMELLIA, which matches all supported cipher suites using any Camellia encryption.
    • 3DES, which matches supported cipher suites using triple DES encryption (see Encryption._3DES).
    • DES, which matches supported cipher suites using plain DES encryption (see Encryption.DES).
    • RC4, which matches supported cipher suites using RC4 encryption (see Encryption.RC4).
    • RC2, which matches supported cipher suites using RC2 encryption (see Encryption.RC2).
    • IDEA, which matches supported cipher suites using IDEA encryption (see Encryption.IDEA).
    • SEED, which matches supported cipher suites using SEED encryption (see Encryption.SEED).
    • MD5, which matches supported cipher suites using the MD5 digest algorithm (see Digest.MD5).
    • SHA1 or SHA, which matches supported cipher suites using the SHA-1 digest algorithm (see Digest.SHA1).
    • SHA256, which matches supported cipher suites using the SHA-256 digest algorithm (see Digest.SHA256).
    • SHA384, which matches supported cipher suites using the SHA-384 digest algorithm (see Digest.SHA384).
    • aGOST, which matches supported cipher suites using GOST authentication.
    • aGOST01, which matches supported cipher suites using GOST R 34.10-2001 authentication (see Authentication.GOST01).
    • aGOST94, which matches supported cipher suites using GOST R 34.10-94 authentication (see Authentication.GOST94).
    • kGOST, which matches supported cipher suites using VKO 34.10 key exchange (see KeyAgreement.GOST).
    • GOST94, which matches supported cipher suites using GOST R 34.11-94 based HMAC (see Digest.GOST94).
    • GOST89MAC, which matches supported cipher suites using GOST 28147-89 based MAC (not HMAC) (see Digest.GOST89MAC).
    • kPSK, which matches supported cipher suites using pre-shared keys key agreement (see KeyAgreement.PSK).
    • aPSK, which matches supported cipher suites using pre-shared keys authentication (see Authentication.PSK).
    • PSK, which matches supported cipher suites using pre-shared keys (see Authentication.PSK and KeyAgreement.PSK).
    • RSAPSK or kRSAPSK, which matches supported cipher suites using RSA-based pre-shared keys (see KeyAgreement.RSAPSK).
    • kEDHPSK, kDHEPSK, EDHPSK or DHEPSK, which matches supported cipher suites using ephemeral DH-based pre-shared keys (see KeyAgreement.DHEPSK).
    • kEECDHPSK, EECDHPSK, kECDHEPSK or ECDHEPSK, which matches supported cipher suites using ephemeral elliptic-curve DH-based pre-shared keys (see KeyAgreement.ECDHEPSK).
  • More than one of any of the above keywords or cipher suite names joined by + symbols, which indicates that all of the items must be matched (i.e. a logical "and" operation).
  • The special unary ! operator followed by any of the above keywords or cipher names, which removes the matching cipher suite(s) from the enabled list and also deletes it from the supported list, preventing any matching cipher suites from being re-added by a later rule.
  • The special unary - operator followed by any of the above keywords or cipher names, which removes the matching cipher suite(s) from the enabled list (though they may still be re-added).
  • The special unary + operator followed by any of the above keywords or cipher names, which causes any of the matching cipher suite(s) to be moved to the end of the list of enabled cipher suites.
  • The special ALL keyword, which includes all cipher suites (except for encryptionless suites; in other words, this keyword implies -eNULL).
  • The special COMPLEMENTOFALL keyword, which is presently equivalent to eNULL.
  • The special DEFAULT keyword, which is equivalent to ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2.
  • The special COMPLEMENTOFDEFAULT keyword, which presently includes any anonymous cipher suites (but excludes those without encryption, which must always be enabled manually).
  • The special @STRENGTH keyword, which causes all the mechanisms enabled thus far to be automatically sorted by encryption algorithm key length.

Parameters:

string - the string to parse

Returns:

the parsed cipher suite selector

Throws:

IllegalArgumentException - if the given string is not valid