1 /*
2 * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26
27 package javax.net.ssl;
28
29 import java.io.IOException;
30 import java.net.*;
31 import java.util.List;
32 import java.util.function.BiFunction;
33
34 /**
35 * This class extends <code>Socket</code> and provides secure
36 * sockets using protocols such as the "Secure
37 * Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.
38 * <P>
39 * Such sockets are normal stream sockets, but they
40 * add a layer of security protections over the underlying network transport
41 * protocol, such as TCP. Those protections include: <UL>
42 *
43 * <LI> <em>Integrity Protection</em>. SSL protects against
44 * modification of messages by an active wiretapper.
45 *
46 * <LI> <em>Authentication</em>. In most modes, SSL provides
47 * peer authentication. Servers are usually authenticated,
48 * and clients may be authenticated as requested by servers.
49 *
50 * <LI> <em>Confidentiality (Privacy Protection)</em>. In most
51 * modes, SSL encrypts data being sent between client and server.
52 * This protects the confidentiality of data, so that passive
53 * wiretappers won't see sensitive data such as financial
54 * information or personal information of many kinds.
55 *
56 * </UL>
57 *
58 * <P>These kinds of protection are specified by a "cipher suite", which
59 * is a combination of cryptographic algorithms used by a given SSL connection.
60 * During the negotiation process, the two endpoints must agree on
61 * a ciphersuite that is available in both environments.
62 * If there is no such suite in common, no SSL connection can
63 * be established, and no data can be exchanged.
64 *
65 * <P> The cipher suite used is established by a negotiation process
66 * called "handshaking". The goal of this
67 * process is to create or rejoin a "session", which may protect many
68 * connections over time. After handshaking has completed, you can access
69 * session attributes by using the <em>getSession</em> method.
70 * The initial handshake on this connection can be initiated in
71 * one of three ways: <UL>
72 *
73 * <LI> calling <code>startHandshake</code> which explicitly
74 * begins handshakes, or
75 * <LI> any attempt to read or write application data on
76 * this socket causes an implicit handshake, or
77 * <LI> a call to <code>getSession</code> tries to set up a session
78 * if there is no currently valid session, and
79 * an implicit handshake is done.
80 * </UL>
81 *
82 * <P>If handshaking fails for any reason, the <code>SSLSocket</code>
83 * is closed, and no further communications can be done.
84 *
85 * <P>There are two groups of cipher suites which you will need to know
86 * about when managing cipher suites: <UL>
87 *
88 * <LI> <em>Supported</em> cipher suites: all the suites which are
89 * supported by the SSL implementation. This list is reported
90 * using <em>getSupportedCipherSuites</em>.
91 *
92 * <LI> <em>Enabled</em> cipher suites, which may be fewer
93 * than the full set of supported suites. This group is
94 * set using the <em>setEnabledCipherSuites</em> method, and
95 * queried using the <em>getEnabledCipherSuites</em> method.
96 * Initially, a default set of cipher suites will be enabled on
97 * a new socket that represents the minimum suggested configuration.
98 *
99 * </UL>
100 *
101 * <P> Implementation defaults require that only cipher
102 * suites which authenticate servers and provide confidentiality
103 * be enabled by default.
104 * Only if both sides explicitly agree to unauthenticated and/or
105 * non-private (unencrypted) communications will such a ciphersuite be
106 * selected.
107 *
108 * <P>When an <code>SSLSocket</code> is first created, no handshaking
109 * is done so that applications may first set their communication
110 * preferences: what cipher suites to use, whether the socket should be
111 * in client or server mode, etc.
112 * However, security is always provided by the time that application data
113 * is sent over the connection.
114 *
115 * <P> You may register to receive event notification of handshake
116 * completion. This involves
117 * the use of two additional classes. <em>HandshakeCompletedEvent</em>
118 * objects are passed to <em>HandshakeCompletedListener</em> instances,
119 * which are registered by users of this API.
120 *
121 * An <code>SSLSocket</code> is created by <code>SSLSocketFactory</code>,
122 * or by <code>accept</code>ing a connection from a
123 * <code>SSLServerSocket</code>.
124 *
125 * <P>A SSL socket must choose to operate in the client or server mode.
126 * This will determine who begins the handshaking process, as well
127 * as which messages should be sent by each party. Each
128 * connection must have one client and one server, or handshaking
129 * will not progress properly. Once the initial handshaking has started, a
130 * socket can not switch between client and server modes, even when
131 * performing renegotiations.
132 *
133 * @apiNote
134 * When the connection is no longer needed, the client and server
135 * applications should each close both sides of their respective connection.
136 * For {@code SSLSocket} objects, for example, an application can call
137 * {@link Socket#shutdownOutput()} or {@link java.io.OutputStream#close()}
138 * for output strean close and call {@link Socket#shutdownInput()} or
139 * {@link java.io.InputStream#close()} for input stream close. Note that
140 * in some cases, closing the input stream may depend on the peer's output
141 * stream being closed first. If the connection is not closed in an orderly
142 * manner (for example {@link Socket#shutdownInput()} is called before the
143 * peer's write closure notification has been received), exceptions may
144 * be raised to indicate that an error has occurred. Once an
145 * {@code SSLSocket} is closed, it is not reusable: a new {@code SSLSocket}
146 * must be created.
147 *
148 * @see java.net.Socket
149 * @see SSLServerSocket
150 * @see SSLSocketFactory
151 *
152 * @since 1.4
153 * @author David Brownell
154 */
155 public abstract class SSLSocket extends Socket
156 {
157 /**
158 * Used only by subclasses.
159 * Constructs an uninitialized, unconnected TCP socket.
160 */
161 protected SSLSocket()
162 { super(); }
163
164
165 /**
166 * Used only by subclasses.
167 * Constructs a TCP connection to a named host at a specified port.
168 * This acts as the SSL client.
169 * <p>
170 * If there is a security manager, its <code>checkConnect</code>
171 * method is called with the host address and <code>port</code>
172 * as its arguments. This could result in a SecurityException.
173 *
174 * @param host name of the host with which to connect, or
175 * <code>null</code> for the loopback address.
176 * @param port number of the server's port
177 * @throws IOException if an I/O error occurs when creating the socket
178 * @throws SecurityException if a security manager exists and its
179 * <code>checkConnect</code> method doesn't allow the operation.
180 * @throws UnknownHostException if the host is not known
181 * @throws IllegalArgumentException if the port parameter is outside the
182 * specified range of valid port values, which is between 0 and
183 * 65535, inclusive.
184 * @see SecurityManager#checkConnect
185 */
186 protected SSLSocket(String host, int port)
187 throws IOException, UnknownHostException
188 { super(host, port); }
189
190
191 /**
192 * Used only by subclasses.
193 * Constructs a TCP connection to a server at a specified address
194 * and port. This acts as the SSL client.
195 * <p>
196 * If there is a security manager, its <code>checkConnect</code>
197 * method is called with the host address and <code>port</code>
198 * as its arguments. This could result in a SecurityException.
199 *
200 * @param address the server's host
201 * @param port its port
202 * @throws IOException if an I/O error occurs when creating the socket
203 * @throws SecurityException if a security manager exists and its
204 * <code>checkConnect</code> method doesn't allow the operation.
205 * @throws IllegalArgumentException if the port parameter is outside the
206 * specified range of valid port values, which is between 0 and
207 * 65535, inclusive.
208 * @throws NullPointerException if <code>address</code> is null.
209 * @see SecurityManager#checkConnect
210 */
211 protected SSLSocket(InetAddress address, int port)
212 throws IOException
213 { super(address, port); }
214
215
216 /**
217 * Used only by subclasses.
218 * Constructs an SSL connection to a named host at a specified port,
219 * binding the client side of the connection a given address and port.
220 * This acts as the SSL client.
221 * <p>
222 * If there is a security manager, its <code>checkConnect</code>
223 * method is called with the host address and <code>port</code>
224 * as its arguments. This could result in a SecurityException.
225 *
226 * @param host name of the host with which to connect, or
227 * <code>null</code> for the loopback address.
228 * @param port number of the server's port
229 * @param clientAddress the client's address the socket is bound to, or
230 * <code>null</code> for the <code>anyLocal</code> address.
231 * @param clientPort the client's port the socket is bound to, or
232 * <code>zero</code> for a system selected free port.
233 * @throws IOException if an I/O error occurs when creating the socket
234 * @throws SecurityException if a security manager exists and its
235 * <code>checkConnect</code> method doesn't allow the operation.
236 * @throws UnknownHostException if the host is not known
237 * @throws IllegalArgumentException if the port parameter or clientPort
238 * parameter is outside the specified range of valid port values,
239 * which is between 0 and 65535, inclusive.
240 * @see SecurityManager#checkConnect
241 */
242 protected SSLSocket(String host, int port,
243 InetAddress clientAddress, int clientPort)
244 throws IOException, UnknownHostException
245 { super(host, port, clientAddress, clientPort); }
246
247
248 /**
249 * Used only by subclasses.
250 * Constructs an SSL connection to a server at a specified address
251 * and TCP port, binding the client side of the connection a given
252 * address and port. This acts as the SSL client.
253 * <p>
254 * If there is a security manager, its <code>checkConnect</code>
255 * method is called with the host address and <code>port</code>
256 * as its arguments. This could result in a SecurityException.
257 *
258 * @param address the server's host
259 * @param port its port
260 * @param clientAddress the client's address the socket is bound to, or
261 * <code>null</code> for the <code>anyLocal</code> address.
262 * @param clientPort the client's port the socket is bound to, or
263 * <code>zero</code> for a system selected free port.
264 * @throws IOException if an I/O error occurs when creating the socket
265 * @throws SecurityException if a security manager exists and its
266 * <code>checkConnect</code> method doesn't allow the operation.
267 * @throws IllegalArgumentException if the port parameter or clientPort
268 * parameter is outside the specified range of valid port values,
269 * which is between 0 and 65535, inclusive.
270 * @throws NullPointerException if <code>address</code> is null.
271 * @see SecurityManager#checkConnect
272 */
273 protected SSLSocket(InetAddress address, int port,
274 InetAddress clientAddress, int clientPort)
275 throws IOException
276 { super(address, port, clientAddress, clientPort); }
277
278
279 /**
280 * Returns the names of the cipher suites which could be enabled for use
281 * on this connection. Normally, only a subset of these will actually
282 * be enabled by default, since this list may include cipher suites which
283 * do not meet quality of service requirements for those defaults. Such
284 * cipher suites might be useful in specialized applications.
285 * <P>
286 * The returned array includes cipher suites from the list of standard
287 * cipher suite names in the <a href=
288 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
289 * JSSE Cipher Suite Names</a> section of the Java Cryptography
290 * Architecture Standard Algorithm Name Documentation, and may also
291 * include other cipher suites that the provider supports.
292 *
293 * @return an array of cipher suite names
294 * @see #getEnabledCipherSuites()
295 * @see #setEnabledCipherSuites(String [])
296 */
297 public abstract String [] getSupportedCipherSuites();
298
299
300 /**
301 * Returns the names of the SSL cipher suites which are currently
302 * enabled for use on this connection. When an SSLSocket is first
303 * created, all enabled cipher suites support a minimum quality of
304 * service. Thus, in some environments this value might be empty.
305 * <P>
306 * Note that even if a suite is enabled, it may never be used. This
307 * can occur if the peer does not support it, or its use is restricted,
308 * or the requisite certificates (and private keys) for the suite are
309 * not available, or an anonymous suite is enabled but authentication
310 * is required.
311 * <P>
312 * The returned array includes cipher suites from the list of standard
313 * cipher suite names in the <a href=
314 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
315 * JSSE Cipher Suite Names</a> section of the Java Cryptography
316 * Architecture Standard Algorithm Name Documentation, and may also
317 * include other cipher suites that the provider supports.
318 *
319 * @return an array of cipher suite names
320 * @see #getSupportedCipherSuites()
321 * @see #setEnabledCipherSuites(String [])
322 */
323 public abstract String [] getEnabledCipherSuites();
324
325
326 /**
327 * Sets the cipher suites enabled for use on this connection.
328 * <P>
329 * Each cipher suite in the <code>suites</code> parameter must have
330 * been listed by getSupportedCipherSuites(), or the method will
331 * fail. Following a successful call to this method, only suites
332 * listed in the <code>suites</code> parameter are enabled for use.
333 * <P>
334 * Note that the standard list of cipher suite names may be found in the
335 * <a href=
336 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
337 * JSSE Cipher Suite Names</a> section of the Java Cryptography
338 * Architecture Standard Algorithm Name Documentation. Providers
339 * may support cipher suite names not found in this list or might not
340 * use the recommended name for a certain cipher suite.
341 * <P>
342 * See {@link #getEnabledCipherSuites()} for more information
343 * on why a specific ciphersuite may never be used on a connection.
344 *
345 * @param suites Names of all the cipher suites to enable
346 * @throws IllegalArgumentException when one or more of the ciphers
347 * named by the parameter is not supported, or when the
348 * parameter is null.
349 * @see #getSupportedCipherSuites()
350 * @see #getEnabledCipherSuites()
351 */
352 public abstract void setEnabledCipherSuites(String suites []);
353
354
355 /**
356 * Returns the names of the protocols which could be enabled for use
357 * on an SSL connection.
358 *
359 * @return an array of protocols supported
360 */
361 public abstract String [] getSupportedProtocols();
362
363
364 /**
365 * Returns the names of the protocol versions which are currently
366 * enabled for use on this connection.
367 * <P>
368 * Note that even if a protocol is enabled, it may never be used.
369 * This can occur if the peer does not support the protocol, or its
370 * use is restricted, or there are no enabled cipher suites supported
371 * by the protocol.
372 *
373 * @see #setEnabledProtocols(String [])
374 * @return an array of protocols
375 */
376 public abstract String [] getEnabledProtocols();
377
378
379 /**
380 * Sets the protocol versions enabled for use on this connection.
381 * <P>
382 * The protocols must have been listed by
383 * <code>getSupportedProtocols()</code> as being supported.
384 * Following a successful call to this method, only protocols listed
385 * in the <code>protocols</code> parameter are enabled for use.
386 *
387 * @param protocols Names of all the protocols to enable.
388 * @throws IllegalArgumentException when one or more of
389 * the protocols named by the parameter is not supported or
390 * when the protocols parameter is null.
391 * @see #getEnabledProtocols()
392 */
393 public abstract void setEnabledProtocols(String protocols[]);
394
395
396 /**
397 * Returns the SSL Session in use by this connection. These can
398 * be long lived, and frequently correspond to an entire login session
399 * for some user. The session specifies a particular cipher suite
400 * which is being actively used by all connections in that session,
401 * as well as the identities of the session's client and server.
402 * <P>
403 * This method will initiate the initial handshake if
404 * necessary and then block until the handshake has been
405 * established.
406 * <P>
407 * If an error occurs during the initial handshake, this method
408 * returns an invalid session object which reports an invalid
409 * cipher suite of "SSL_NULL_WITH_NULL_NULL".
410 *
411 * @return the <code>SSLSession</code>
412 */
413 public abstract SSLSession getSession();
414
415
416 /**
417 * Returns the {@code SSLSession} being constructed during a SSL/TLS
418 * handshake.
419 * <p>
420 * TLS protocols may negotiate parameters that are needed when using
421 * an instance of this class, but before the {@code SSLSession} has
422 * been completely initialized and made available via {@code getSession}.
423 * For example, the list of valid signature algorithms may restrict
424 * the type of certificates that can used during TrustManager
425 * decisions, or the maximum TLS fragment packet sizes can be
426 * resized to better support the network environment.
427 * <p>
428 * This method provides early access to the {@code SSLSession} being
429 * constructed. Depending on how far the handshake has progressed,
430 * some data may not yet be available for use. For example, if a
431 * remote server will be sending a Certificate chain, but that chain
432 * has yet not been processed, the {@code getPeerCertificates}
433 * method of {@code SSLSession} will throw a
434 * SSLPeerUnverifiedException. Once that chain has been processed,
435 * {@code getPeerCertificates} will return the proper value.
436 * <p>
437 * Unlike {@link #getSession()}, this method does not initiate the
438 * initial handshake and does not block until handshaking is
439 * complete.
440 *
441 * @see SSLEngine
442 * @see SSLSession
443 * @see ExtendedSSLSession
444 * @see X509ExtendedKeyManager
445 * @see X509ExtendedTrustManager
446 *
447 * @return null if this instance is not currently handshaking, or
448 * if the current handshake has not progressed far enough to
449 * create a basic SSLSession. Otherwise, this method returns the
450 * {@code SSLSession} currently being negotiated.
451 * @throws UnsupportedOperationException if the underlying provider
452 * does not implement the operation.
453 *
454 * @since 1.7
455 */
456 public SSLSession getHandshakeSession() {
457 throw new UnsupportedOperationException();
458 }
459
460
461 /**
462 * Registers an event listener to receive notifications that an
463 * SSL handshake has completed on this connection.
464 *
465 * @param listener the HandShake Completed event listener
466 * @see #startHandshake()
467 * @see #removeHandshakeCompletedListener(HandshakeCompletedListener)
468 * @throws IllegalArgumentException if the argument is null.
469 */
470 public abstract void addHandshakeCompletedListener(
471 HandshakeCompletedListener listener);
472
473
474 /**
475 * Removes a previously registered handshake completion listener.
476 *
477 * @param listener the HandShake Completed event listener
478 * @throws IllegalArgumentException if the listener is not registered,
479 * or the argument is null.
480 * @see #addHandshakeCompletedListener(HandshakeCompletedListener)
481 */
482 public abstract void removeHandshakeCompletedListener(
483 HandshakeCompletedListener listener);
484
485
486 /**
487 * Starts an SSL handshake on this connection. Common reasons include
488 * a need to use new encryption keys, to change cipher suites, or to
489 * initiate a new session. To force complete reauthentication, the
490 * current session could be invalidated before starting this handshake.
491 *
492 * <P> If data has already been sent on the connection, it continues
493 * to flow during this handshake. When the handshake completes, this
494 * will be signaled with an event.
495 *
496 * This method is synchronous for the initial handshake on a connection
497 * and returns when the negotiated handshake is complete. Some
498 * protocols may not support multiple handshakes on an existing socket
499 * and may throw an IOException.
500 *
501 * @throws IOException on a network level error
502 * @see #addHandshakeCompletedListener(HandshakeCompletedListener)
503 */
504 public abstract void startHandshake() throws IOException;
505
506
507 /**
508 * Configures the socket to use client (or server) mode when
509 * handshaking.
510 * <P>
511 * This method must be called before any handshaking occurs.
512 * Once handshaking has begun, the mode can not be reset for the
513 * life of this socket.
514 * <P>
515 * Servers normally authenticate themselves, and clients
516 * are not required to do so.
517 *
518 * @param mode true if the socket should start its handshaking
519 * in "client" mode
520 * @throws IllegalArgumentException if a mode change is attempted
521 * after the initial handshake has begun.
522 * @see #getUseClientMode()
523 */
524 public abstract void setUseClientMode(boolean mode);
525
526
527 /**
528 * Returns true if the socket is set to use client mode when
529 * handshaking.
530 *
531 * @return true if the socket should do handshaking
532 * in "client" mode
533 * @see #setUseClientMode(boolean)
534 */
535 public abstract boolean getUseClientMode();
536
537
538 /**
539 * Configures the socket to <i>require</i> client authentication. This
540 * option is only useful for sockets in the server mode.
541 * <P>
542 * A socket's client authentication setting is one of the following:
543 * <ul>
544 * <li> client authentication required
545 * <li> client authentication requested
546 * <li> no client authentication desired
547 * </ul>
548 * <P>
549 * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and
550 * the client chooses not to provide authentication information
551 * about itself, <i>the negotiations will stop and the connection
552 * will be dropped</i>.
553 * <P>
554 * Calling this method overrides any previous setting made by
555 * this method or {@link #setWantClientAuth(boolean)}.
556 *
557 * @param need set to true if client authentication is required,
558 * or false if no client authentication is desired.
559 * @see #getNeedClientAuth()
560 * @see #setWantClientAuth(boolean)
561 * @see #getWantClientAuth()
562 * @see #setUseClientMode(boolean)
563 */
564 public abstract void setNeedClientAuth(boolean need);
565
566
567 /**
568 * Returns true if the socket will <i>require</i> client authentication.
569 * This option is only useful to sockets in the server mode.
570 *
571 * @return true if client authentication is required,
572 * or false if no client authentication is desired.
573 * @see #setNeedClientAuth(boolean)
574 * @see #setWantClientAuth(boolean)
575 * @see #getWantClientAuth()
576 * @see #setUseClientMode(boolean)
577 */
578 public abstract boolean getNeedClientAuth();
579
580
581 /**
582 * Configures the socket to <i>request</i> client authentication.
583 * This option is only useful for sockets in the server mode.
584 * <P>
585 * A socket's client authentication setting is one of the following:
586 * <ul>
587 * <li> client authentication required
588 * <li> client authentication requested
589 * <li> no client authentication desired
590 * </ul>
591 * <P>
592 * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and
593 * the client chooses not to provide authentication information
594 * about itself, <i>the negotiations will continue</i>.
595 * <P>
596 * Calling this method overrides any previous setting made by
597 * this method or {@link #setNeedClientAuth(boolean)}.
598 *
599 * @param want set to true if client authentication is requested,
600 * or false if no client authentication is desired.
601 * @see #getWantClientAuth()
602 * @see #setNeedClientAuth(boolean)
603 * @see #getNeedClientAuth()
604 * @see #setUseClientMode(boolean)
605 */
606 public abstract void setWantClientAuth(boolean want);
607
608
609 /**
610 * Returns true if the socket will <i>request</i> client authentication.
611 * This option is only useful for sockets in the server mode.
612 *
613 * @return true if client authentication is requested,
614 * or false if no client authentication is desired.
615 * @see #setNeedClientAuth(boolean)
616 * @see #getNeedClientAuth()
617 * @see #setWantClientAuth(boolean)
618 * @see #setUseClientMode(boolean)
619 */
620 public abstract boolean getWantClientAuth();
621
622
623 /**
624 * Controls whether new SSL sessions may be established by this socket.
625 * If session creations are not allowed, and there are no
626 * existing sessions to resume, there will be no successful
627 * handshaking.
628 *
629 * @param flag true indicates that sessions may be created; this
630 * is the default. false indicates that an existing session
631 * must be resumed
632 * @see #getEnableSessionCreation()
633 */
634 public abstract void setEnableSessionCreation(boolean flag);
635
636
637 /**
638 * Returns true if new SSL sessions may be established by this socket.
639 *
640 * @return true indicates that sessions may be created; this
641 * is the default. false indicates that an existing session
642 * must be resumed
643 * @see #setEnableSessionCreation(boolean)
644 */
645 public abstract boolean getEnableSessionCreation();
646
647 /**
648 * Returns the SSLParameters in effect for this SSLSocket.
649 * The ciphersuites and protocols of the returned SSLParameters
650 * are always non-null.
651 *
652 * @return the SSLParameters in effect for this SSLSocket.
653 * @since 1.6
654 */
655 public SSLParameters getSSLParameters() {
656 SSLParameters params = new SSLParameters();
657 params.setCipherSuites(getEnabledCipherSuites());
658 params.setProtocols(getEnabledProtocols());
659 if (getNeedClientAuth()) {
660 params.setNeedClientAuth(true);
661 } else if (getWantClientAuth()) {
662 params.setWantClientAuth(true);
663 }
664 return params;
665 }
666
667 /**
668 * Applies SSLParameters to this socket.
669 *
670 * <p>This means:
671 * <ul>
672 * <li>If {@code params.getCipherSuites()} is non-null,
673 * {@code setEnabledCipherSuites()} is called with that value.</li>
674 * <li>If {@code params.getProtocols()} is non-null,
675 * {@code setEnabledProtocols()} is called with that value.</li>
676 * <li>If {@code params.getNeedClientAuth()} or
677 * {@code params.getWantClientAuth()} return {@code true},
678 * {@code setNeedClientAuth(true)} and
679 * {@code setWantClientAuth(true)} are called, respectively;
680 * otherwise {@code setWantClientAuth(false)} is called.</li>
681 * <li>If {@code params.getServerNames()} is non-null, the socket will
682 * configure its server names with that value.</li>
683 * <li>If {@code params.getSNIMatchers()} is non-null, the socket will
684 * configure its SNI matchers with that value.</li>
685 * </ul>
686 *
687 * @param params the parameters
688 * @throws IllegalArgumentException if the setEnabledCipherSuites() or
689 * the setEnabledProtocols() call fails
690 * @since 1.6
691 */
692 public void setSSLParameters(SSLParameters params) {
693 String[] s;
694 s = params.getCipherSuites();
695 if (s != null) {
696 setEnabledCipherSuites(s);
697 }
698 s = params.getProtocols();
699 if (s != null) {
700 setEnabledProtocols(s);
701 }
702 if (params.getNeedClientAuth()) {
703 setNeedClientAuth(true);
704 } else if (params.getWantClientAuth()) {
705 setWantClientAuth(true);
706 } else {
707 setWantClientAuth(false);
708 }
709 }
710
711 /**
712 * Returns the most recent application protocol value negotiated for this
713 * connection.
714 * <p>
715 * If supported by the underlying SSL/TLS/DTLS implementation,
716 * application name negotiation mechanisms such as <a
717 * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 </a>, the
718 * Application-Layer Protocol Negotiation (ALPN), can negotiate
719 * application-level values between peers.
720 *
721 * @implSpec
722 * The implementation in this class throws
723 * {@code UnsupportedOperationException} and performs no other action.
724 *
725 * @return null if it has not yet been determined if application
726 * protocols might be used for this connection, an empty
727 * {@code String} if application protocols values will not
728 * be used, or a non-empty application protocol {@code String}
729 * if a value was successfully negotiated.
730 * @throws UnsupportedOperationException if the underlying provider
731 * does not implement the operation.
732 * @since 9
733 */
734 public String getApplicationProtocol() {
735 throw new UnsupportedOperationException();
736 }
737
738 /**
739 * Returns the application protocol value negotiated on a SSL/TLS
740 * handshake currently in progress.
741 * <p>
742 * Like {@link #getHandshakeSession()},
743 * a connection may be in the middle of a handshake. The
744 * application protocol may or may not yet be available.
745 *
746 * @implSpec
747 * The implementation in this class throws
748 * {@code UnsupportedOperationException} and performs no other action.
749 *
750 * @return null if it has not yet been determined if application
751 * protocols might be used for this handshake, an empty
752 * {@code String} if application protocols values will not
753 * be used, or a non-empty application protocol {@code String}
754 * if a value was successfully negotiated.
755 * @throws UnsupportedOperationException if the underlying provider
756 * does not implement the operation.
757 * @since 9
758 */
759 public String getHandshakeApplicationProtocol() {
760 throw new UnsupportedOperationException();
761 }
762
763
764 /**
765 * Registers a callback function that selects an application protocol
766 * value for a SSL/TLS/DTLS handshake.
767 * The function overrides any values supplied using
768 * {@link SSLParameters#setApplicationProtocols
769 * SSLParameters.setApplicationProtocols} and it supports the following
770 * type parameters:
771 * <blockquote>
772 * <dl>
773 * <dt> {@code SSLSocket}
774 * <dd> The function's first argument allows the current {@code SSLSocket}
775 * to be inspected, including the handshake session and configuration
776 * settings.
777 * <dt> {@code List<String>}
778 * <dd> The function's second argument lists the application protocol names
779 * advertised by the TLS peer.
780 * <dt> {@code String}
781 * <dd> The function's result is an application protocol name, or null to
782 * indicate that none of the advertised names are acceptable.
783 * If the return value is an empty {@code String} then application
784 * protocol indications will not be used.
785 * If the return value is null (no value chosen) or is a value that
786 * was not advertised by the peer, the underlying protocol will
787 * determine what action to take. (For example, ALPN will send a
788 * "no_application_protocol" alert and terminate the connection.)
789 * </dl>
790 * </blockquote>
791 *
792 * For example, the following call registers a callback function that
793 * examines the TLS handshake parameters and selects an application protocol
794 * name:
795 * <pre>{@code
796 * serverSocket.setHandshakeApplicationProtocolSelector(
797 * (serverSocket, clientProtocols) -> {
798 * SSLSession session = serverSocket.getHandshakeSession();
799 * return chooseApplicationProtocol(
800 * serverSocket,
801 * clientProtocols,
802 * session.getProtocol(),
803 * session.getCipherSuite());
804 * });
805 * }</pre>
806 *
807 * @apiNote
808 * This method should be called by TLS server applications before the TLS
809 * handshake begins. Also, this {@code SSLSocket} should be configured with
810 * parameters that are compatible with the application protocol selected by
811 * the callback function. For example, enabling a poor choice of cipher
812 * suites could result in no suitable application protocol.
813 * See {@link SSLParameters}.
814 *
815 * @implSpec
816 * The implementation in this class throws
817 * {@code UnsupportedOperationException} and performs no other action.
818 *
819 * @param selector the callback function, or null to de-register.
820 * @throws UnsupportedOperationException if the underlying provider
821 * does not implement the operation.
822 * @since 9
823 */
824 public void setHandshakeApplicationProtocolSelector(
825 BiFunction<SSLSocket, List<String>, String> selector) {
826 throw new UnsupportedOperationException();
827 }
828
829 /**
830 * Retrieves the callback function that selects an application protocol
831 * value during a SSL/TLS/DTLS handshake.
832 * See {@link #setHandshakeApplicationProtocolSelector
833 * setHandshakeApplicationProtocolSelector}
834 * for the function's type parameters.
835 *
836 * @implSpec
837 * The implementation in this class throws
838 * {@code UnsupportedOperationException} and performs no other action.
839 *
840 * @return the callback function, or null if none has been set.
841 * @throws UnsupportedOperationException if the underlying provider
842 * does not implement the operation.
843 * @since 9
844 */
845 public BiFunction<SSLSocket, List<String>, String>
846 getHandshakeApplicationProtocolSelector() {
847 throw new UnsupportedOperationException();
848 }
849 }