SSLParameters (Java Platform SE 8 )
Keywords: javax.net.ssl.SSLParameters class
Date: 2017-01-22

compact1, compact2, compact3
javax.net.ssl

## Class SSLParameters

- java.lang.Object
- - javax.net.ssl.SSLParameters

-     public class SSLParameters
      extends Object

  Encapsulates parameters for an SSL/TLS connection. The parameters are the list of ciphersuites to be accepted in an SSL/TLS handshake, the list of protocols to be allowed, the endpoint identification algorithm during SSL/TLS handshaking, the Server Name Indication (SNI), the algorithm constraints and whether SSL/TLS servers should request or require client authentication, etc.

  SSLParameters can be created via the constructors in this class. Objects can also be obtained using the `getSSLParameters()` methods in `SSLSocket` and `SSLServerSocket` and `SSLEngine` or the `getDefaultSSLParameters()` and `getSupportedSSLParameters()` methods in `SSLContext`.

  SSLParameters can be applied to a connection via the methods `SSLSocket.setSSLParameters()` and `SSLServerSocket.setSSLParameters()` and `SSLEngine.setSSLParameters()`.

  Since:
    1.6
  See Also:
    `SSLSocket`, `SSLEngine`, `SSLContext`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SSLParameters()` Constructs SSLParameters.
    `SSLParameters(String[] cipherSuites)` Constructs SSLParameters from the specified array of ciphersuites.
    `SSLParameters(String[] cipherSuites, String[] protocols)` Constructs SSLParameters from the specified array of ciphersuites and protocols.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `AlgorithmConstraints` | `getAlgorithmConstraints()` Returns the cryptographic algorithm constraints.
    `String[]` | `getCipherSuites()` Returns a copy of the array of ciphersuites or null if none have been set.
    `String` | `getEndpointIdentificationAlgorithm()` Gets the endpoint identification algorithm.
    `boolean` | `getNeedClientAuth()` Returns whether client authentication should be required.
    `String[]` | `getProtocols()` Returns a copy of the array of protocols or null if none have been set.
    `List<SNIServerName>` | `getServerNames()` Returns a `List` containing all `SNIServerName`s of the Server Name Indication (SNI) parameter, or null if none has been set.
    `Collection<SNIMatcher>` | `getSNIMatchers()` Returns a `Collection` containing all `SNIMatcher`s of the Server Name Indication (SNI) parameter, or null if none has been set.
    `boolean` | `getUseCipherSuitesOrder()` Returns whether the local cipher suites preference should be honored.
    `boolean` | `getWantClientAuth()` Returns whether client authentication should be requested.
    `void` | `setAlgorithmConstraints(AlgorithmConstraints constraints)` Sets the cryptographic algorithm constraints, which will be used in addition to any configured by the runtime environment.
    `void` | `setCipherSuites(String[] cipherSuites)` Sets the array of ciphersuites.
    `void` | `setEndpointIdentificationAlgorithm(String algorithm)` Sets the endpoint identification algorithm.
    `void` | `setNeedClientAuth(boolean needClientAuth)` Sets whether client authentication should be required.
    `void` | `setProtocols(String[] protocols)` Sets the array of protocols.
    `void` | `setServerNames(List<SNIServerName> serverNames)` Sets the desired `SNIServerName`s of the Server Name Indication (SNI) parameter.
    `void` | `setSNIMatchers(Collection<SNIMatcher> matchers)` Sets the `SNIMatcher`s of the Server Name Indication (SNI) parameter.
    `void` | `setUseCipherSuitesOrder(boolean honorOrder)` Sets whether the local cipher suites preference should be honored.
    `void` | `setWantClientAuth(boolean wantClientAuth)` Sets whether client authentication should be requested.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### SSLParameters

          public SSLParameters()

      Constructs SSLParameters.

      The values of cipherSuites, protocols, cryptographic algorithm constraints, endpoint identification algorithm, server names and server name matchers are set to `null`, useCipherSuitesOrder, wantClientAuth and needClientAuth are set to `false`.

    - #### SSLParameters

          public SSLParameters(String[] cipherSuites)

      Constructs SSLParameters from the specified array of ciphersuites.

      Calling this constructor is equivalent to calling the no-args constructor followed by `setCipherSuites(cipherSuites);`.

      Parameters:
        `cipherSuites` - the array of ciphersuites (or null)

    - #### SSLParameters

          public SSLParameters(String[] cipherSuites,
                               String[] protocols)

      Constructs SSLParameters from the specified array of ciphersuites and protocols.

      Calling this constructor is equivalent to calling the no-args constructor followed by `setCipherSuites(cipherSuites); setProtocols(protocols);`.

      Parameters:
        `cipherSuites` - the array of ciphersuites (or null)
        `protocols` - the array of protocols (or null)

  - ### Method Detail

    - #### getCipherSuites

          public String[] getCipherSuites()

      Returns a copy of the array of ciphersuites or null if none have been set.
      Returns:
        a copy of the array of ciphersuites or null if none have been set.

    - #### setCipherSuites

          public void setCipherSuites(String[] cipherSuites)

      Sets the array of ciphersuites.
      Parameters:
        `cipherSuites` - the array of ciphersuites (or null)

    - #### getProtocols

          public String[] getProtocols()

      Returns a copy of the array of protocols or null if none have been set.
      Returns:
        a copy of the array of protocols or null if none have been set.

    - #### setProtocols

          public void setProtocols(String[] protocols)

      Sets the array of protocols.
      Parameters:
        `protocols` - the array of protocols (or null)

    - #### getWantClientAuth

          public boolean getWantClientAuth()

      Returns whether client authentication should be requested.
      Returns:
        whether client authentication should be requested.

    - #### setWantClientAuth

          public void setWantClientAuth(boolean wantClientAuth)

      Sets whether client authentication should be requested. Calling this method clears the `needClientAuth` flag.
      Parameters:
        `wantClientAuth` - whether client authentication should be requested

    - #### getNeedClientAuth

          public boolean getNeedClientAuth()

      Returns whether client authentication should be required.
      Returns:
        whether client authentication should be required.

    - #### setNeedClientAuth

          public void setNeedClientAuth(boolean needClientAuth)

      Sets whether client authentication should be required. Calling this method clears the `wantClientAuth` flag.
      Parameters:
        `needClientAuth` - whether client authentication should be required

    - #### getAlgorithmConstraints

          public AlgorithmConstraints getAlgorithmConstraints()

      Returns the cryptographic algorithm constraints.
      Returns:
        the cryptographic algorithm constraints, or null if the constraints have not been set
      Since:
        1.7
      See Also:
        `setAlgorithmConstraints(AlgorithmConstraints)`

    - #### setAlgorithmConstraints

          public void setAlgorithmConstraints(AlgorithmConstraints constraints)

      Sets the cryptographic algorithm constraints, which will be used in addition to any configured by the runtime environment.

      If the `constraints` parameter is non-null, every cryptographic algorithm, key and algorithm parameters used in the SSL/TLS handshake must be permitted by the constraints.

      Parameters:
        `constraints` - the algorithm constraints (or null)
      Since:
        1.7

    - #### getEndpointIdentificationAlgorithm

          public String getEndpointIdentificationAlgorithm()

      Gets the endpoint identification algorithm.
      Returns:
        the endpoint identification algorithm, or null if none has been set.
      Since:
        1.7
      See Also:
        `X509ExtendedTrustManager`, `setEndpointIdentificationAlgorithm(String)`

    - #### setEndpointIdentificationAlgorithm

          public void setEndpointIdentificationAlgorithm(String algorithm)

      Sets the endpoint identification algorithm.

      If the `algorithm` parameter is non-null or non-empty, the endpoint identification/verification procedures must be handled during SSL/TLS handshaking. This is to prevent man-in-the-middle attacks.

      Parameters:
        `algorithm` - The standard string name of the endpoint identification algorithm (or null). See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
      Since:
        1.7
      See Also:
        `X509ExtendedTrustManager`

    - #### setServerNames

          public final void setServerNames(List<SNIServerName> serverNames)

      Sets the desired `SNIServerName`s of the Server Name Indication (SNI) parameter.

      This method is only useful to `SSLSocket`s or `SSLEngine`s operating in client mode.

      Note that the `serverNames` list is cloned to protect against subsequent modification.

      Parameters:
        `serverNames` - the list of desired `SNIServerName`s (or null)
      Throws:
        `NullPointerException` - if the `serverNames` contains `null` element
        `IllegalArgumentException` - if the `serverNames` contains more than one name of the same name type
      Since:
        1.8
      See Also:
        `SNIServerName`, `getServerNames()`

    - #### getServerNames

          public final List<SNIServerName> getServerNames()

      Returns a `List` containing all `SNIServerName`s of the Server Name Indication (SNI) parameter, or null if none has been set.

      This method is only useful to `SSLSocket`s or `SSLEngine`s operating in client mode.

      For SSL/TLS connections, the underlying SSL/TLS provider may specify a default value for a certain server name type. In client mode, it is recommended that, by default, providers should include the server name indication whenever the server can be located by a supported server name type.

      It is recommended that providers initialize default Server Name Indications when creating `SSLSocket`/`SSLEngine`s. In the following examples, the server name could be represented by an instance of `SNIHostName` which has been initialized with the hostname "www.example.com" and type `StandardConstants.SNI_HOST_NAME`.

               Socket socket =
                   sslSocketFactory.createSocket("www.example.com", 443);

      or

               SSLEngine engine =
                   sslContext.createSSLEngine("www.example.com", 443);

      Returns:
        null or an immutable list of non-null `SNIServerName`s
      Since:
        1.8
      See Also:
        `List`, `setServerNames(List)`

    - #### setSNIMatchers

          public final void setSNIMatchers(Collection<SNIMatcher> matchers)

      Sets the `SNIMatcher`s of the Server Name Indication (SNI) parameter.

      This method is only useful to `SSLSocket`s or `SSLEngine`s operating in server mode.

      Note that the `matchers` collection is cloned to protect against subsequent modification.

      Parameters:
        `matchers` - the collection of `SNIMatcher`s (or null)
      Throws:
        `NullPointerException` - if the `matchers` contains `null` element
        `IllegalArgumentException` - if the `matchers` contains more than one name of the same name type
      Since:
        1.8
      See Also:
        `Collection`, `SNIMatcher`, `getSNIMatchers()`

    - #### getSNIMatchers

          public final Collection<SNIMatcher> getSNIMatchers()

      Returns a `Collection` containing all `SNIMatcher`s of the Server Name Indication (SNI) parameter, or null if none has been set.

      This method is only useful to `SSLSocket`s or `SSLEngine`s operating in server mode.

      For better interoperability, providers generally will not define default matchers so that by default servers will ignore the SNI extension and continue the handshake.

      Returns:
        null or an immutable collection of non-null `SNIMatcher`s
      Since:
        1.8
      See Also:
        `SNIMatcher`, `setSNIMatchers(Collection)`

    - #### setUseCipherSuitesOrder

          public final void setUseCipherSuitesOrder(boolean honorOrder)

      Sets whether the local cipher suites preference should be honored.
      Parameters:
        `honorOrder` - whether local cipher suites order in `#getCipherSuites` should be honored during SSL/TLS handshaking.
      Since:
        1.8
      See Also:
        `getUseCipherSuitesOrder()`

    - #### getUseCipherSuitesOrder

          public final boolean getUseCipherSuitesOrder()

      Returns whether the local cipher suites preference should be honored.
      Returns:
        whether local cipher suites order in `#getCipherSuites` should be honored during SSL/TLS handshaking.
      Since:
        1.8
      See Also:
        `setUseCipherSuitesOrder(boolean)`

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.