Package org.wildfly.security.ssl

Class CipherSuiteSelector

  • public abstract class CipherSuiteSelector
extends Object
    An immutable filter for SSL/TLS cipher suites.
    Author:
    David M. Lloyd

    • Field Detail

      • OPENSSL_DEFAULT_CIPHER_SUITE_NAMES

        public static final String OPENSSL_DEFAULT_CIPHER_SUITE_NAMES
        OpenSSL default cipher suites for TLSv1.3.
        See Also:
        Constant Field Values

    • Method Detail

      • empty

        public static CipherSuiteSelector empty()
        Get the basic empty SSL cipher suite selector.
        Returns:
        the empty selector

      • empty

        public static CipherSuiteSelector empty​(boolean useTLS13)
        Get the basic empty SSL cipher suite selector.
        Parameters:
        useTLS13 - true if the TLSv1.3 mechanism database should be used by this selector and false otherwise
        Returns:
        the empty selector

      • openSslDefaultCipherSuites

        public static CipherSuiteSelector openSslDefaultCipherSuites()
        Get the cipher selector which OpenSSL defines as the default cipher suites for TLSv1.3.
        Returns:
        the selector

      • openSslCombinedDefault

        public static CipherSuiteSelector openSslCombinedDefault()
        Get the cipher selector which OpenSSL defines as DEFAULT combined with the cipher suites which OpenSSL defines as the default cipher suites for TLSv1.3.
        Returns:
        the selector

      • 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

      • evaluate

        public 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 in descending order.
        Parameters:
        string - the string to parse
        Returns:
        the parsed cipher suite selector
        Throws:
        IllegalArgumentException - if the given string is not valid

      • fromNamesString

        public static CipherSuiteSelector fromNamesString​(String names)
                                           throws IllegalArgumentException
        Create a cipher suite selector from the given OpenSSL-style TLSv1.3 cipher suites string. The format for this string is a simple colon (":") separated list of TLSv1.3 cipher suite names.
        Parameters:
        names - the string to parse
        Returns:
        the parsed cipher suite selector
        Throws:
        IllegalArgumentException - if the given string is not valid

      • aggregate

        public static CipherSuiteSelector aggregate​(CipherSuiteSelector cipherSuiteSelector1,
                                            CipherSuiteSelector cipherSuiteSelector2)
        Create an aggregate CipherSuiteSelector. Each cipher suite selector is executed in order.
        Parameters:
        cipherSuiteSelector1 - the first cipher suite selector
        cipherSuiteSelector2 - the second cipher suite selector
        Returns:
        the aggregate cipher suite selector (not null)