* SSLParameters can be created via the constructors in this class. * Objects can also be obtained using the {@code getSSLParameters()} * methods in * {@link SSLSocket#getSSLParameters SSLSocket} and * {@link SSLServerSocket#getSSLParameters SSLServerSocket} and * {@link SSLEngine#getSSLParameters SSLEngine} or the * {@link SSLContext#getDefaultSSLParameters getDefaultSSLParameters()} and * {@link SSLContext#getSupportedSSLParameters getSupportedSSLParameters()} * methods in {@code SSLContext}. *
* SSLParameters can be applied to a connection via the methods * {@link SSLSocket#setSSLParameters SSLSocket.setSSLParameters()} and * {@link SSLServerSocket#setSSLParameters SSLServerSocket.setSSLParameters()} * and {@link SSLEngine#setSSLParameters SSLEngine.setSSLParameters()}. *
* For example: * *
* SSLParameters p = sslSocket.getSSLParameters();
* p.setProtocols(new String[] { "TLSv1.2" });
* p.setCipherSuites(
* new String[] { "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", ... });
* p.setApplicationProtocols(new String[] {"h2", "http/1.1"});
* sslSocket.setSSLParameters(p);
* * The values of cipherSuites, protocols, cryptographic algorithm * constraints, endpoint identification algorithm, server names and * server name matchers are set to {@code null}; useCipherSuitesOrder, * wantClientAuth and needClientAuth are set to {@code false}; * enableRetransmissions is set to {@code true}; maximum network packet * size is set to {@code 0}. */ public SSLParameters() { // empty } /** * Constructs SSLParameters from the specified array of ciphersuites. *
* Calling this constructor is equivalent to calling the no-args * constructor followed by * {@code setCipherSuites(cipherSuites);}. Note that the * standard list of cipher suite names may be found in the * JSSE Cipher Suite Names section of the Java Cryptography * Architecture Standard Algorithm Name Documentation. Providers * may support cipher suite names not found in this list. * * @param cipherSuites the array of ciphersuites (or null) */ public SSLParameters(String[] cipherSuites) { setCipherSuites(cipherSuites); } /** * Constructs SSLParameters from the specified array of ciphersuites * and protocols. *
* Calling this constructor is equivalent to calling the no-args * constructor followed by * {@code setCipherSuites(cipherSuites); setProtocols(protocols);}. * Note that the standard list of cipher suite names may be found in the * * JSSE Cipher Suite Names section of the Java Cryptography * Architecture Standard Algorithm Name Documentation. Providers * may support cipher suite names not found in this list. * * @param cipherSuites the array of ciphersuites (or null) * @param protocols the array of protocols (or null) */ public SSLParameters(String[] cipherSuites, String[] protocols) { setCipherSuites(cipherSuites); setProtocols(protocols); } private static String[] clone(String[] s) { return (s == null) ? null : s.clone(); } /** * Returns a copy of the array of ciphersuites or null if none * have been set. *
* The returned array includes cipher suites from the list of standard * cipher suite names in the * JSSE Cipher Suite Names section of the Java Cryptography * Architecture Standard Algorithm Name Documentation, and may also * include other cipher suites that the provider supports. * * @return a copy of the array of ciphersuites or null if none * have been set. */ public String[] getCipherSuites() { return clone(cipherSuites); } /** * Sets the array of ciphersuites. * * @param cipherSuites the array of ciphersuites (or null). Note that the * standard list of cipher suite names may be found in the * JSSE Cipher Suite Names section of the Java Cryptography * Architecture Standard Algorithm Name Documentation. Providers * may support cipher suite names not found in this list or might not * use the recommended name for a certain cipher suite. */ public void setCipherSuites(String[] cipherSuites) { this.cipherSuites = clone(cipherSuites); } /** * Returns a copy of the array of protocols or null if none * have been set. * * @return a copy of the array of protocols or null if none * have been set. */ public String[] getProtocols() { return clone(protocols); } /** * Sets the array of protocols. * * @param protocols the array of protocols (or null) */ public void setProtocols(String[] protocols) { this.protocols = clone(protocols); } /** * Returns whether client authentication should be requested. * * @return whether client authentication should be requested. */ public boolean getWantClientAuth() { return wantClientAuth; } /** * Sets whether client authentication should be requested. Calling * this method clears the {@code needClientAuth} flag. * * @param wantClientAuth whether client authentication should be requested */ public void setWantClientAuth(boolean wantClientAuth) { this.wantClientAuth = wantClientAuth; this.needClientAuth = false; } /** * Returns whether client authentication should be required. * * @return whether client authentication should be required. */ public boolean getNeedClientAuth() { return needClientAuth; } /** * Sets whether client authentication should be required. Calling * this method clears the {@code wantClientAuth} flag. * * @param needClientAuth whether client authentication should be required */ public void setNeedClientAuth(boolean needClientAuth) { this.wantClientAuth = false; this.needClientAuth = needClientAuth; } /** * Returns the cryptographic algorithm constraints. * * @return the cryptographic algorithm constraints, or null if the * constraints have not been set * * @see #setAlgorithmConstraints(AlgorithmConstraints) * * @since 1.7 */ public AlgorithmConstraints getAlgorithmConstraints() { return algorithmConstraints; } /** * Sets the cryptographic algorithm constraints, which will be used * in addition to any configured by the runtime environment. *
* If the {@code constraints} parameter is non-null, every * cryptographic algorithm, key and algorithm parameters used in the * SSL/TLS/DTLS handshake must be permitted by the constraints. * * @param constraints the algorithm constraints (or null) * * @since 1.7 */ public void setAlgorithmConstraints(AlgorithmConstraints constraints) { // the constraints object is immutable this.algorithmConstraints = constraints; } /** * Gets the endpoint identification algorithm. * * @return the endpoint identification algorithm, or null if none * has been set. * * @see X509ExtendedTrustManager * @see #setEndpointIdentificationAlgorithm(String) * * @since 1.7 */ public String getEndpointIdentificationAlgorithm() { return identificationAlgorithm; } /** * Sets the endpoint identification algorithm. *
* If the {@code algorithm} parameter is non-null or non-empty, the * endpoint identification/verification procedures must be handled during * SSL/TLS/DTLS handshaking. This is to prevent man-in-the-middle attacks. * * @param algorithm The standard string name of the endpoint * identification algorithm (or null). * See the * Java Security Standard Algorithm Names document * for information about standard algorithm names. * * @see X509ExtendedTrustManager * * @since 1.7 */ public void setEndpointIdentificationAlgorithm(String algorithm) { this.identificationAlgorithm = algorithm; } /** * Sets the desired {@link SNIServerName}s of the Server Name * Indication (SNI) parameter. *
* This method is only useful to {@link SSLSocket}s or {@link SSLEngine}s * operating in client mode. *
* Note that the {@code serverNames} list is cloned
* to protect against subsequent modification.
*
* @param serverNames
* the list of desired {@link SNIServerName}s (or null)
*
* @throws NullPointerException if the {@code serverNames}
* contains {@code null} element
* @throws IllegalArgumentException if the {@code serverNames}
* contains more than one name of the same name type
*
* @see SNIServerName
* @see #getServerNames()
*
* @since 1.8
*/
public final void setServerNames(List
* This method is only useful to {@link SSLSocket}s or {@link SSLEngine}s
* operating in client mode.
*
* For SSL/TLS/DTLS connections, the underlying SSL/TLS/DTLS 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 {@code SSLSocket}/{@code SSLEngine}s.
* In the following examples, the server name could be represented by an
* instance of {@link SNIHostName} which has been initialized with the
* hostname "www.example.com" and type
* {@link StandardConstants#SNI_HOST_NAME}.
*
*
* This method is only useful to {@link SSLSocket}s or {@link SSLEngine}s
* operating in server mode.
*
* Note that the {@code matchers} collection is cloned to protect
* against subsequent modification.
*
* @param matchers
* the collection of {@link SNIMatcher}s (or null)
*
* @throws NullPointerException if the {@code matchers}
* contains {@code null} element
* @throws IllegalArgumentException if the {@code matchers}
* contains more than one name of the same name type
*
* @see Collection
* @see SNIMatcher
* @see #getSNIMatchers()
*
* @since 1.8
*/
public final void setSNIMatchers(Collection
* This method is only useful to {@link SSLSocket}s or {@link 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.
*
* @return null or an immutable collection of non-null {@link SNIMatcher}s
*
* @see SNIMatcher
* @see #setSNIMatchers(Collection)
*
* @since 1.8
*/
public final Collection
* An implementation should attempt to comply with the maximum
* packet size configuration. However, if the maximum packet
* size is too small to hold a minimal record, an implementation
* may try to generate as minimal records as possible. This
* may cause a generated packet to be larger than the maximum
* packet size.
*
* @return the maximum expected network packet size, or {@code 0} if
* use the implicit size that is automatically specified by
* the underlying implementation and this object has not been
* populated by any connection.
*
* @see #setMaximumPacketSize(int)
*
* @since 9
*/
public int getMaximumPacketSize() {
return maximumPacketSize;
}
/**
* Returns a prioritized array of application-layer protocol names that
* can be negotiated over the SSL/TLS/DTLS protocols.
*
* The array could be empty (zero-length), in which case protocol
* indications will not be used.
*
* This method will return a new array each time it is invoked.
*
* @return a non-null, possibly zero-length array of application protocol
* {@code String}s. The array is ordered based on protocol
* preference, with {@code protocols[0]} being the most preferred.
* @see #setApplicationProtocols
* @since 9
*/
public String[] getApplicationProtocols() {
return applicationProtocols.clone();
}
/**
* Sets the prioritized array of application-layer protocol names that
* can be negotiated over the SSL/TLS/DTLS protocols.
*
* If application-layer protocols are supported by the underlying
* SSL/TLS implementation, this method configures which values can
* be negotiated by protocols such as RFC 7301 , the
* Application Layer Protocol Negotiation (ALPN).
*
* If this end of the connection is expected to offer application protocol
* values, all protocols configured by this method will be sent to the
* peer.
*
* If this end of the connection is expected to select the application
* protocol value, the {@code protocols} configured by this method are
* compared with those sent by the peer. The first matched value becomes
* the negotiated value. If none of the {@code protocols} were actually
* requested by the peer, the underlying protocol will determine what
* action to take. (For example, ALPN will send a
* {@code "no_application_protocol"} alert and terminate the connection.)
*
* @implSpec
* This method will make a copy of the {@code protocols} array.
*
* @param protocols an ordered array of application protocols,
* with {@code protocols[0]} being the most preferred.
* If the array is empty (zero-length), protocol
* indications will not be used.
* @throws IllegalArgumentException if protocols is null, or if
* any element in a non-empty array is null or an
* empty (zero-length) string
* @see #getApplicationProtocols
* @since 9
*/
public void setApplicationProtocols(String[] protocols) {
if (protocols == null) {
throw new IllegalArgumentException("protocols was null");
}
String[] tempProtocols = protocols.clone();
for (String p : tempProtocols) {
if (p == null || p.isEmpty()) {
throw new IllegalArgumentException(
"An element of protocols was null/empty");
}
}
applicationProtocols = tempProtocols;
}
}
* Socket socket =
* sslSocketFactory.createSocket("www.example.com", 443);
*
* or
*
* SSLEngine engine =
* sslContext.createSSLEngine("www.example.com", 443);
*
*
* @return null or an immutable list of non-null {@link SNIServerName}s
*
* @see List
* @see #setServerNames(List)
*
* @since 1.8
*/
public final List