1 /*
2 * Copyright (c) 2003, 2017, 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 package javax.net.ssl;
27
28 import java.nio.ByteBuffer;
29 import java.nio.ReadOnlyBufferException;
30 import java.util.List;
31 import java.util.function.BiFunction;
32
33
34 /**
35 * A class which enables secure communications using protocols such as
36 * the Secure Sockets Layer (SSL) or
37 * <A HREF="http://www.ietf.org/rfc/rfc2246.txt"> IETF RFC 2246 "Transport
38 * Layer Security" (TLS) </A> protocols, but is transport independent.
39 * <P>
40 * The secure communications modes include: <UL>
41 *
42 * <LI> <em>Integrity Protection</em>. SSL/TLS/DTLS protects against
43 * modification of messages by an active wiretapper.
44 *
45 * <LI> <em>Authentication</em>. In most modes, SSL/TLS/DTLS provides
46 * peer authentication. Servers are usually authenticated, and
47 * clients may be authenticated as requested by servers.
48 *
49 * <LI> <em>Confidentiality (Privacy Protection)</em>. In most
50 * modes, SSL/TLS/DTLS encrypts data being sent between client and
51 * server. This protects the confidentiality of data, so that
52 * passive wiretappers won't see sensitive data such as financial
53 * information or personal information of many kinds.
54 *
55 * </UL>
56 *
57 * These kinds of protection are specified by a "cipher suite", which
58 * is a combination of cryptographic algorithms used by a given SSL
59 * connection. During the negotiation process, the two endpoints must
60 * agree on a cipher suite that is available in both environments. If
61 * there is no such suite in common, no SSL connection can be
62 * established, and no data can be exchanged.
63 * <P>
64 * The cipher suite used is established by a negotiation process called
65 * "handshaking". The goal of this process is to create or rejoin a
66 * "session", which may protect many connections over time. After
67 * handshaking has completed, you can access session attributes by
68 * using the {@link #getSession()} method.
69 * <P>
70 * The {@code SSLSocket} class provides much of the same security
71 * functionality, but all of the inbound and outbound data is
72 * automatically transported using the underlying {@link
73 * java.net.Socket Socket}, which by design uses a blocking model.
74 * While this is appropriate for many applications, this model does not
75 * provide the scalability required by large servers.
76 * <P>
77 * The primary distinction of an {@code SSLEngine} is that it
78 * operates on inbound and outbound byte streams, independent of the
79 * transport mechanism. It is the responsibility of the
80 * {@code SSLEngine} user to arrange for reliable I/O transport to
81 * the peer. By separating the SSL/TLS/DTLS abstraction from the I/O
82 * transport mechanism, the {@code SSLEngine} can be used for a
83 * wide variety of I/O types, such as {@link
84 * java.nio.channels.spi.AbstractSelectableChannel#configureBlocking(boolean)
85 * non-blocking I/O (polling)}, {@link java.nio.channels.Selector
86 * selectable non-blocking I/O}, {@link java.net.Socket Socket} and the
87 * traditional Input/OutputStreams, local {@link java.nio.ByteBuffer
88 * ByteBuffers} or byte arrays, <A
89 * HREF="http://www.jcp.org/en/jsr/detail?id=203"> future asynchronous
90 * I/O models </A>, and so on.
91 * <P>
92 * At a high level, the {@code SSLEngine} appears thus:
93 *
94 * <pre>
95 * app data
96 *
97 * | ^
98 * | | |
99 * v | |
100 * +----+-----|-----+----+
101 * | | |
102 * | SSL|Engine |
103 * wrap() | | | unwrap()
104 * | OUTBOUND | INBOUND |
105 * | | |
106 * +----+-----|-----+----+
107 * | | ^
108 * | | |
109 * v |
110 *
111 * net data
112 * </pre>
113 * Application data (also known as plaintext or cleartext) is data which
114 * is produced or consumed by an application. Its counterpart is
115 * network data, which consists of either handshaking and/or ciphertext
116 * (encrypted) data, and destined to be transported via an I/O
117 * mechanism. Inbound data is data which has been received from the
118 * peer, and outbound data is destined for the peer.
119 * <P>
120 * (In the context of an {@code SSLEngine}, the term "handshake
121 * data" is taken to mean any data exchanged to establish and control a
122 * secure connection. Handshake data includes the SSL/TLS/DTLS messages
123 * "alert", "change_cipher_spec," and "handshake.")
124 * <P>
125 * There are five distinct phases to an {@code SSLEngine}.
126 *
127 * <OL>
128 * <li> Creation - The {@code SSLEngine} has been created and
129 * initialized, but has not yet been used. During this phase, an
130 * application may set any {@code SSLEngine}-specific settings
131 * (enabled cipher suites, whether the {@code SSLEngine} should
132 * handshake in client or server mode, and so on). Once
133 * handshaking has begun, though, any new settings (except
134 * client/server mode, see below) will be used for
135 * the next handshake.
136 *
137 * <li> Initial Handshake - The initial handshake is a procedure by
138 * which the two peers exchange communication parameters until an
139 * SSLSession is established. Application data can not be sent during
140 * this phase.
141 *
142 * <li> Application Data - Once the communication parameters have
143 * been established and the handshake is complete, application data
144 * may flow through the {@code SSLEngine}. Outbound
145 * application messages are encrypted and integrity protected,
146 * and inbound messages reverse the process.
147 *
148 * <li> Rehandshaking - Either side may request a renegotiation of
149 * the session at any time during the Application Data phase. New
150 * handshaking data can be intermixed among the application data.
151 * Before starting the rehandshake phase, the application may
152 * reset the SSL/TLS/DTLS communication parameters such as the list of
153 * enabled ciphersuites and whether to use client authentication,
154 * but can not change between client/server modes. As before, once
155 * handshaking has begun, any new {@code SSLEngine}
156 * configuration settings will not be used until the next
157 * handshake.
158 *
159 * <li> Closure - When the connection is no longer needed, the
160 * application should close the {@code SSLEngine} and should
161 * send/receive any remaining messages to the peer before
162 * closing the underlying transport mechanism. Once an engine is
163 * closed, it is not reusable: a new {@code SSLEngine} must
164 * be created.
165 * </OL>
166 * An {@code SSLEngine} is created by calling {@link
167 * SSLContext#createSSLEngine()} from an initialized
168 * {@code SSLContext}. Any configuration
169 * parameters should be set before making the first call to
170 * {@code wrap()}, {@code unwrap()}, or
171 * {@code beginHandshake()}. These methods all trigger the
172 * initial handshake.
173 * <P>
174 * Data moves through the engine by calling {@link #wrap(ByteBuffer,
175 * ByteBuffer) wrap()} or {@link #unwrap(ByteBuffer, ByteBuffer)
176 * unwrap()} on outbound or inbound data, respectively. Depending on
177 * the state of the {@code SSLEngine}, a {@code wrap()} call
178 * may consume application data from the source buffer and may produce
179 * network data in the destination buffer. The outbound data
180 * may contain application and/or handshake data. A call to
181 * {@code unwrap()} will examine the source buffer and may
182 * advance the handshake if the data is handshaking information, or
183 * may place application data in the destination buffer if the data
184 * is application. The state of the underlying SSL/TLS/DTLS algorithm
185 * will determine when data is consumed and produced.
186 * <P>
187 * Calls to {@code wrap()} and {@code unwrap()} return an
188 * {@code SSLEngineResult} which indicates the status of the
189 * operation, and (optionally) how to interact with the engine to make
190 * progress.
191 * <P>
192 * The {@code SSLEngine} produces/consumes complete SSL/TLS/DTLS
193 * packets only, and does not store application data internally between
194 * calls to {@code wrap()/unwrap()}. Thus input and output
195 * {@code ByteBuffer}s must be sized appropriately to hold the
196 * maximum record that can be produced. Calls to {@link
197 * SSLSession#getPacketBufferSize()} and {@link
198 * SSLSession#getApplicationBufferSize()} should be used to determine
199 * the appropriate buffer sizes. The size of the outbound application
200 * data buffer generally does not matter. If buffer conditions do not
201 * allow for the proper consumption/production of data, the application
202 * must determine (via {@link SSLEngineResult}) and correct the
203 * problem, and then try the call again.
204 * <P>
205 * For example, {@code unwrap()} will return a {@link
206 * SSLEngineResult.Status#BUFFER_OVERFLOW} result if the engine
207 * determines that there is not enough destination buffer space available.
208 * Applications should call {@link SSLSession#getApplicationBufferSize()}
209 * and compare that value with the space available in the destination buffer,
210 * enlarging the buffer if necessary. Similarly, if {@code unwrap()}
211 * were to return a {@link SSLEngineResult.Status#BUFFER_UNDERFLOW}, the
212 * application should call {@link SSLSession#getPacketBufferSize()} to ensure
213 * that the source buffer has enough room to hold a record (enlarging if
214 * necessary), and then obtain more inbound data.
215 *
216 * <pre>{@code
217 * SSLEngineResult r = engine.unwrap(src, dst);
218 * switch (r.getStatus()) {
219 * BUFFER_OVERFLOW:
220 * // Could attempt to drain the dst buffer of any already obtained
221 * // data, but we'll just increase it to the size needed.
222 * int appSize = engine.getSession().getApplicationBufferSize();
223 * ByteBuffer b = ByteBuffer.allocate(appSize + dst.position());
224 * dst.flip();
225 * b.put(dst);
226 * dst = b;
227 * // retry the operation.
228 * break;
229 * BUFFER_UNDERFLOW:
230 * int netSize = engine.getSession().getPacketBufferSize();
231 * // Resize buffer if needed.
232 * if (netSize > dst.capacity()) {
233 * ByteBuffer b = ByteBuffer.allocate(netSize);
234 * src.flip();
235 * b.put(src);
236 * src = b;
237 * }
238 * // Obtain more inbound network data for src,
239 * // then retry the operation.
240 * break;
241 * // other cases: CLOSED, OK.
242 * }
243 * }</pre>
244 *
245 * <P>
246 * Unlike {@code SSLSocket}, all methods of SSLEngine are
247 * non-blocking. {@code SSLEngine} implementations may
248 * require the results of tasks that may take an extended period of
249 * time to complete, or may even block. For example, a TrustManager
250 * may need to connect to a remote certificate validation service,
251 * or a KeyManager might need to prompt a user to determine which
252 * certificate to use as part of client authentication. Additionally,
253 * creating cryptographic signatures and verifying them can be slow,
254 * seemingly blocking.
255 * <P>
256 * For any operation which may potentially block, the
257 * {@code SSLEngine} will create a {@link java.lang.Runnable}
258 * delegated task. When {@code SSLEngineResult} indicates that a
259 * delegated task result is needed, the application must call {@link
260 * #getDelegatedTask()} to obtain an outstanding delegated task and
261 * call its {@link java.lang.Runnable#run() run()} method (possibly using
262 * a different thread depending on the compute strategy). The
263 * application should continue obtaining delegated tasks until no more
264 * exist, and try the original operation again.
265 * <P>
266 * At the end of a communication session, applications should properly
267 * close the SSL/TLS/DTLS link. The SSL/TLS/DTLS protocols have closure
268 * handshake messages, and these messages should be communicated to the
269 * peer before releasing the {@code SSLEngine} and closing the
270 * underlying transport mechanism. A close can be initiated by one of:
271 * an SSLException, an inbound closure handshake message, or one of the
272 * close methods. In all cases, closure handshake messages are
273 * generated by the engine, and {@code wrap()} should be repeatedly
274 * called until the resulting {@code SSLEngineResult}'s status
275 * returns "CLOSED", or {@link #isOutboundDone()} returns true. All
276 * data obtained from the {@code wrap()} method should be sent to the
277 * peer.
278 * <P>
279 * {@link #closeOutbound()} is used to signal the engine that the
280 * application will not be sending any more data.
281 * <P>
282 * A peer will signal its intent to close by sending its own closure
283 * handshake message. After this message has been received and
284 * processed by the local {@code SSLEngine}'s {@code unwrap()}
285 * call, the application can detect the close by calling
286 * {@code unwrap()} and looking for a {@code SSLEngineResult}
287 * with status "CLOSED", or if {@link #isInboundDone()} returns true.
288 * If for some reason the peer closes the communication link without
289 * sending the proper SSL/TLS/DTLS closure message, the application can
290 * detect the end-of-stream and can signal the engine via {@link
291 * #closeInbound()} that there will no more inbound messages to
292 * process. Some applications might choose to require orderly shutdown
293 * messages from a peer, in which case they can check that the closure
294 * was generated by a handshake message and not by an end-of-stream
295 * condition.
296 * <P>
297 * There are two groups of cipher suites which you will need to know
298 * about when managing cipher suites:
299 *
300 * <UL>
301 * <LI> <em>Supported</em> cipher suites: all the suites which are
302 * supported by the SSL implementation. This list is reported
303 * using {@link #getSupportedCipherSuites()}.
304 *
305 * <LI> <em>Enabled</em> cipher suites, which may be fewer than
306 * the full set of supported suites. This group is set using the
307 * {@link #setEnabledCipherSuites(String [])} method, and
308 * queried using the {@link #getEnabledCipherSuites()} method.
309 * Initially, a default set of cipher suites will be enabled on a
310 * new engine that represents the minimum suggested
311 * configuration.
312 * </UL>
313 *
314 * Implementation defaults require that only cipher suites which
315 * authenticate servers and provide confidentiality be enabled by
316 * default. Only if both sides explicitly agree to unauthenticated
317 * and/or non-private (unencrypted) communications will such a
318 * cipher suite be selected.
319 * <P>
320 * Each SSL/TLS/DTLS connection must have one client and one server, thus
321 * each endpoint must decide which role to assume. This choice determines
322 * who begins the handshaking process as well as which type of messages
323 * should be sent by each party. The method {@link
324 * #setUseClientMode(boolean)} configures the mode. Once the initial
325 * handshaking has started, an {@code SSLEngine} can not switch
326 * between client and server modes, even when performing renegotiations.
327 * <P>
328 * Applications might choose to process delegated tasks in different
329 * threads. When an {@code SSLEngine}
330 * is created, the current {@link java.security.AccessControlContext}
331 * is saved. All future delegated tasks will be processed using this
332 * context: that is, all access control decisions will be made using the
333 * context captured at engine creation.
334 *
335 * <HR>
336 *
337 * <B>Concurrency Notes</B>:
338 * There are two concurrency issues to be aware of:
339 *
340 * <OL>
341 * <li>The {@code wrap()} and {@code unwrap()} methods
342 * may execute concurrently of each other.
343 *
344 * <li> The SSL/TLS/DTLS protocols employ ordered packets.
345 * Applications must take care to ensure that generated packets
346 * are delivered in sequence. If packets arrive
347 * out-of-order, unexpected or fatal results may occur.
348 * <P>
349 * For example:
350 *
351 * <pre>
352 * synchronized (outboundLock) {
353 * sslEngine.wrap(src, dst);
354 * outboundQueue.put(dst);
355 * }
356 * </pre>
357 *
358 * As a corollary, two threads must not attempt to call the same method
359 * (either {@code wrap()} or {@code unwrap()}) concurrently,
360 * because there is no way to guarantee the eventual packet ordering.
361 * </OL>
362 *
363 * @see SSLContext
364 * @see SSLSocket
365 * @see SSLServerSocket
366 * @see SSLSession
367 * @see java.net.Socket
368 *
369 * @since 1.5
370 * @author Brad R. Wetmore
371 */
372
373 public abstract class SSLEngine {
374
375 private String peerHost = null;
376 private int peerPort = -1;
377
378 /**
379 * Constructor for an {@code SSLEngine} providing no hints
380 * for an internal session reuse strategy.
381 *
382 * @see SSLContext#createSSLEngine()
383 * @see SSLSessionContext
384 */
385 protected SSLEngine() {
386 }
387
388 /**
389 * Constructor for an {@code SSLEngine}.
390 * <P>
391 * {@code SSLEngine} implementations may use the
392 * {@code peerHost} and {@code peerPort} parameters as hints
393 * for their internal session reuse strategy.
394 * <P>
395 * Some cipher suites (such as Kerberos) require remote hostname
396 * information. Implementations of this class should use this
397 * constructor to use Kerberos.
398 * <P>
399 * The parameters are not authenticated by the
400 * {@code SSLEngine}.
401 *
402 * @param peerHost the name of the peer host
403 * @param peerPort the port number of the peer
404 * @see SSLContext#createSSLEngine(String, int)
405 * @see SSLSessionContext
406 */
407 protected SSLEngine(String peerHost, int peerPort) {
408 this.peerHost = peerHost;
409 this.peerPort = peerPort;
410 }
411
412 /**
413 * Returns the host name of the peer.
414 * <P>
415 * Note that the value is not authenticated, and should not be
416 * relied upon.
417 *
418 * @return the host name of the peer, or null if nothing is
419 * available.
420 */
421 public String getPeerHost() {
422 return peerHost;
423 }
424
425 /**
426 * Returns the port number of the peer.
427 * <P>
428 * Note that the value is not authenticated, and should not be
429 * relied upon.
430 *
431 * @return the port number of the peer, or -1 if nothing is
432 * available.
433 */
434 public int getPeerPort() {
435 return peerPort;
436 }
437
438 /**
439 * Attempts to encode a buffer of plaintext application data into
440 * SSL/TLS/DTLS network data.
441 * <P>
442 * An invocation of this method behaves in exactly the same manner
443 * as the invocation:
444 * <blockquote><pre>
445 * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
446 * engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);}
447 * </pre></blockquote>
448 *
449 * @param src
450 * a {@code ByteBuffer} containing outbound application data
451 * @param dst
452 * a {@code ByteBuffer} to hold outbound network data
453 * @return an {@code SSLEngineResult} describing the result
454 * of this operation.
455 * @throws SSLException
456 * A problem was encountered while processing the
457 * data that caused the {@code SSLEngine} to abort.
458 * See the class description for more information on
459 * engine closure.
460 * @throws ReadOnlyBufferException
461 * if the {@code dst} buffer is read-only.
462 * @throws IllegalArgumentException
463 * if either {@code src} or {@code dst}
464 * is null.
465 * @throws IllegalStateException if the client/server mode
466 * has not yet been set.
467 * @see #wrap(ByteBuffer [], int, int, ByteBuffer)
468 */
469 public SSLEngineResult wrap(ByteBuffer src,
470 ByteBuffer dst) throws SSLException {
471 return wrap(new ByteBuffer [] { src }, 0, 1, dst);
472 }
473
474 /**
475 * Attempts to encode plaintext bytes from a sequence of data
476 * buffers into SSL/TLS/DTLS network data.
477 * <P>
478 * An invocation of this method behaves in exactly the same manner
479 * as the invocation:
480 * <blockquote><pre>
481 * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
482 * engine.wrap(srcs, 0, srcs.length, dst);}
483 * </pre></blockquote>
484 *
485 * @param srcs
486 * an array of {@code ByteBuffers} containing the
487 * outbound application data
488 * @param dst
489 * a {@code ByteBuffer} to hold outbound network data
490 * @return an {@code SSLEngineResult} describing the result
491 * of this operation.
492 * @throws SSLException
493 * A problem was encountered while processing the
494 * data that caused the {@code SSLEngine} to abort.
495 * See the class description for more information on
496 * engine closure.
497 * @throws ReadOnlyBufferException
498 * if the {@code dst} buffer is read-only.
499 * @throws IllegalArgumentException
500 * if either {@code srcs} or {@code dst}
501 * is null, or if any element in {@code srcs} is null.
502 * @throws IllegalStateException if the client/server mode
503 * has not yet been set.
504 * @see #wrap(ByteBuffer [], int, int, ByteBuffer)
505 */
506 public SSLEngineResult wrap(ByteBuffer [] srcs,
507 ByteBuffer dst) throws SSLException {
508 if (srcs == null) {
509 throw new IllegalArgumentException("src == null");
510 }
511 return wrap(srcs, 0, srcs.length, dst);
512 }
513
514
515 /**
516 * Attempts to encode plaintext bytes from a subsequence of data
517 * buffers into SSL/TLS/DTLS network data. This <i>"gathering"</i>
518 * operation encodes, in a single invocation, a sequence of bytes
519 * from one or more of a given sequence of buffers. Gathering
520 * wraps are often useful when implementing network protocols or
521 * file formats that, for example, group data into segments
522 * consisting of one or more fixed-length headers followed by a
523 * variable-length body. See
524 * {@link java.nio.channels.GatheringByteChannel} for more
525 * information on gathering, and {@link
526 * java.nio.channels.GatheringByteChannel#write(ByteBuffer[],
527 * int, int)} for more information on the subsequence
528 * behavior.
529 * <P>
530 * Depending on the state of the SSLEngine, this method may produce
531 * network data without consuming any application data (for example,
532 * it may generate handshake data.)
533 * <P>
534 * The application is responsible for reliably transporting the
535 * network data to the peer, and for ensuring that data created by
536 * multiple calls to wrap() is transported in the same order in which
537 * it was generated. The application must properly synchronize
538 * multiple calls to this method.
539 * <P>
540 * If this {@code SSLEngine} has not yet started its initial
541 * handshake, this method will automatically start the handshake.
542 * <P>
543 * This method will attempt to produce SSL/TLS/DTLS records, and will
544 * consume as much source data as possible, but will never consume
545 * more than the sum of the bytes remaining in each buffer. Each
546 * {@code ByteBuffer}'s position is updated to reflect the
547 * amount of data consumed or produced. The limits remain the
548 * same.
549 * <P>
550 * The underlying memory used by the {@code srcs} and
551 * {@code dst ByteBuffer}s must not be the same.
552 * <P>
553 * See the class description for more information on engine closure.
554 *
555 * @param srcs
556 * an array of {@code ByteBuffers} containing the
557 * outbound application data
558 * @param offset
559 * The offset within the buffer array of the first buffer from
560 * which bytes are to be retrieved; it must be non-negative
561 * and no larger than {@code srcs.length}
562 * @param length
563 * The maximum number of buffers to be accessed; it must be
564 * non-negative and no larger than
565 * {@code srcs.length} - {@code offset}
566 * @param dst
567 * a {@code ByteBuffer} to hold outbound network data
568 * @return an {@code SSLEngineResult} describing the result
569 * of this operation.
570 * @throws SSLException
571 * A problem was encountered while processing the
572 * data that caused the {@code SSLEngine} to abort.
573 * See the class description for more information on
574 * engine closure.
575 * @throws IndexOutOfBoundsException
576 * if the preconditions on the {@code offset} and
577 * {@code length} parameters do not hold.
578 * @throws ReadOnlyBufferException
579 * if the {@code dst} buffer is read-only.
580 * @throws IllegalArgumentException
581 * if either {@code srcs} or {@code dst}
582 * is null, or if any element in the {@code srcs}
583 * subsequence specified is null.
584 * @throws IllegalStateException if the client/server mode
585 * has not yet been set.
586 * @see java.nio.channels.GatheringByteChannel
587 * @see java.nio.channels.GatheringByteChannel#write(
588 * ByteBuffer[], int, int)
589 */
590 public abstract SSLEngineResult wrap(ByteBuffer [] srcs, int offset,
591 int length, ByteBuffer dst) throws SSLException;
592
593 /**
594 * Attempts to decode SSL/TLS/DTLS network data into a plaintext
595 * application data buffer.
596 * <P>
597 * An invocation of this method behaves in exactly the same manner
598 * as the invocation:
599 * <blockquote><pre>
600 * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
601 * engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);}
602 * </pre></blockquote>
603 *
604 * @param src
605 * a {@code ByteBuffer} containing inbound network data.
606 * @param dst
607 * a {@code ByteBuffer} to hold inbound application data.
608 * @return an {@code SSLEngineResult} describing the result
609 * of this operation.
610 * @throws SSLException
611 * A problem was encountered while processing the
612 * data that caused the {@code SSLEngine} to abort.
613 * See the class description for more information on
614 * engine closure.
615 * @throws ReadOnlyBufferException
616 * if the {@code dst} buffer is read-only.
617 * @throws IllegalArgumentException
618 * if either {@code src} or {@code dst}
619 * is null.
620 * @throws IllegalStateException if the client/server mode
621 * has not yet been set.
622 * @see #unwrap(ByteBuffer, ByteBuffer [], int, int)
623 */
624 public SSLEngineResult unwrap(ByteBuffer src,
625 ByteBuffer dst) throws SSLException {
626 return unwrap(src, new ByteBuffer [] { dst }, 0, 1);
627 }
628
629 /**
630 * Attempts to decode SSL/TLS/DTLS network data into a sequence of plaintext
631 * application data buffers.
632 * <P>
633 * An invocation of this method behaves in exactly the same manner
634 * as the invocation:
635 * <blockquote><pre>
636 * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
637 * engine.unwrap(src, dsts, 0, dsts.length);}
638 * </pre></blockquote>
639 *
640 * @param src
641 * a {@code ByteBuffer} containing inbound network data.
642 * @param dsts
643 * an array of {@code ByteBuffer}s to hold inbound
644 * application data.
645 * @return an {@code SSLEngineResult} describing the result
646 * of this operation.
647 * @throws SSLException
648 * A problem was encountered while processing the
649 * data that caused the {@code SSLEngine} to abort.
650 * See the class description for more information on
651 * engine closure.
652 * @throws ReadOnlyBufferException
653 * if any of the {@code dst} buffers are read-only.
654 * @throws IllegalArgumentException
655 * if either {@code src} or {@code dsts}
656 * is null, or if any element in {@code dsts} is null.
657 * @throws IllegalStateException if the client/server mode
658 * has not yet been set.
659 * @see #unwrap(ByteBuffer, ByteBuffer [], int, int)
660 */
661 public SSLEngineResult unwrap(ByteBuffer src,
662 ByteBuffer [] dsts) throws SSLException {
663 if (dsts == null) {
664 throw new IllegalArgumentException("dsts == null");
665 }
666 return unwrap(src, dsts, 0, dsts.length);
667 }
668
669 /**
670 * Attempts to decode SSL/TLS/DTLS network data into a subsequence of
671 * plaintext application data buffers. This <i>"scattering"</i>
672 * operation decodes, in a single invocation, a sequence of bytes
673 * into one or more of a given sequence of buffers. Scattering
674 * unwraps are often useful when implementing network protocols or
675 * file formats that, for example, group data into segments
676 * consisting of one or more fixed-length headers followed by a
677 * variable-length body. See
678 * {@link java.nio.channels.ScatteringByteChannel} for more
679 * information on scattering, and {@link
680 * java.nio.channels.ScatteringByteChannel#read(ByteBuffer[],
681 * int, int)} for more information on the subsequence
682 * behavior.
683 * <P>
684 * Depending on the state of the SSLEngine, this method may consume
685 * network data without producing any application data (for example,
686 * it may consume handshake data.)
687 * <P>
688 * The application is responsible for reliably obtaining the network
689 * data from the peer, and for invoking unwrap() on the data in the
690 * order it was received. The application must properly synchronize
691 * multiple calls to this method.
692 * <P>
693 * If this {@code SSLEngine} has not yet started its initial
694 * handshake, this method will automatically start the handshake.
695 * <P>
696 * This method will attempt to consume one complete SSL/TLS/DTLS network
697 * packet, but will never consume more than the sum of the bytes
698 * remaining in the buffers. Each {@code ByteBuffer}'s
699 * position is updated to reflect the amount of data consumed or
700 * produced. The limits remain the same.
701 * <P>
702 * The underlying memory used by the {@code src} and
703 * {@code dsts ByteBuffer}s must not be the same.
704 * <P>
705 * The inbound network buffer may be modified as a result of this
706 * call: therefore if the network data packet is required for some
707 * secondary purpose, the data should be duplicated before calling this
708 * method. Note: the network data will not be useful to a second
709 * SSLEngine, as each SSLEngine contains unique random state which
710 * influences the SSL/TLS/DTLS messages.
711 * <P>
712 * See the class description for more information on engine closure.
713 *
714 * @param src
715 * a {@code ByteBuffer} containing inbound network data.
716 * @param dsts
717 * an array of {@code ByteBuffer}s to hold inbound
718 * application data.
719 * @param offset
720 * The offset within the buffer array of the first buffer from
721 * which bytes are to be transferred; it must be non-negative
722 * and no larger than {@code dsts.length}.
723 * @param length
724 * The maximum number of buffers to be accessed; it must be
725 * non-negative and no larger than
726 * {@code dsts.length} - {@code offset}.
727 * @return an {@code SSLEngineResult} describing the result
728 * of this operation.
729 * @throws SSLException
730 * A problem was encountered while processing the
731 * data that caused the {@code SSLEngine} to abort.
732 * See the class description for more information on
733 * engine closure.
734 * @throws IndexOutOfBoundsException
735 * If the preconditions on the {@code offset} and
736 * {@code length} parameters do not hold.
737 * @throws ReadOnlyBufferException
738 * if any of the {@code dst} buffers are read-only.
739 * @throws IllegalArgumentException
740 * if either {@code src} or {@code dsts}
741 * is null, or if any element in the {@code dsts}
742 * subsequence specified is null.
743 * @throws IllegalStateException if the client/server mode
744 * has not yet been set.
745 * @see java.nio.channels.ScatteringByteChannel
746 * @see java.nio.channels.ScatteringByteChannel#read(
747 * ByteBuffer[], int, int)
748 */
749 public abstract SSLEngineResult unwrap(ByteBuffer src,
750 ByteBuffer [] dsts, int offset, int length) throws SSLException;
751
752
753 /**
754 * Returns a delegated {@code Runnable} task for
755 * this {@code SSLEngine}.
756 * <P>
757 * {@code SSLEngine} operations may require the results of
758 * operations that block, or may take an extended period of time to
759 * complete. This method is used to obtain an outstanding {@link
760 * java.lang.Runnable} operation (task). Each task must be assigned
761 * a thread (possibly the current) to perform the {@link
762 * java.lang.Runnable#run() run} operation. Once the
763 * {@code run} method returns, the {@code Runnable} object
764 * is no longer needed and may be discarded.
765 * <P>
766 * Delegated tasks run in the {@code AccessControlContext}
767 * in place when this object was created.
768 * <P>
769 * A call to this method will return each outstanding task
770 * exactly once.
771 * <P>
772 * Multiple delegated tasks can be run in parallel.
773 *
774 * @return a delegated {@code Runnable} task, or null
775 * if none are available.
776 */
777 public abstract Runnable getDelegatedTask();
778
779
780 /**
781 * Signals that no more inbound network data will be sent
782 * to this {@code SSLEngine}.
783 * <P>
784 * If the application initiated the closing process by calling
785 * {@link #closeOutbound()}, under some circumstances it is not
786 * required that the initiator wait for the peer's corresponding
787 * close message. (See section 7.2.1 of the TLS specification (<A
788 * HREF="http://www.ietf.org/rfc/rfc2246.txt">RFC 2246</A>) for more
789 * information on waiting for closure alerts.) In such cases, this
790 * method need not be called.
791 * <P>
792 * But if the application did not initiate the closure process, or
793 * if the circumstances above do not apply, this method should be
794 * called whenever the end of the SSL/TLS/DTLS data stream is reached.
795 * This ensures closure of the inbound side, and checks that the
796 * peer followed the SSL/TLS/DTLS close procedure properly, thus
797 * detecting possible truncation attacks.
798 * <P>
799 * This method is idempotent: if the inbound side has already
800 * been closed, this method does not do anything.
801 * <P>
802 * {@link #wrap(ByteBuffer, ByteBuffer) wrap()} should be
803 * called to flush any remaining handshake data.
804 *
805 * @throws SSLException
806 * if this engine has not received the proper SSL/TLS/DTLS close
807 * notification message from the peer.
808 *
809 * @see #isInboundDone()
810 * @see #isOutboundDone()
811 */
812 public abstract void closeInbound() throws SSLException;
813
814
815 /**
816 * Returns whether {@link #unwrap(ByteBuffer, ByteBuffer)} will
817 * accept any more inbound data messages.
818 *
819 * @return true if the {@code SSLEngine} will not
820 * consume anymore network data (and by implication,
821 * will not produce any more application data.)
822 * @see #closeInbound()
823 */
824 public abstract boolean isInboundDone();
825
826
827 /**
828 * Signals that no more outbound application data will be sent
829 * on this {@code SSLEngine}.
830 * <P>
831 * This method is idempotent: if the outbound side has already
832 * been closed, this method does not do anything.
833 * <P>
834 * {@link #wrap(ByteBuffer, ByteBuffer)} should be
835 * called to flush any remaining handshake data.
836 *
837 * @see #isOutboundDone()
838 */
839 public abstract void closeOutbound();
840
841
842 /**
843 * Returns whether {@link #wrap(ByteBuffer, ByteBuffer)} will
844 * produce any more outbound data messages.
845 * <P>
846 * Note that during the closure phase, a {@code SSLEngine} may
847 * generate handshake closure data that must be sent to the peer.
848 * {@code wrap()} must be called to generate this data. When
849 * this method returns true, no more outbound data will be created.
850 *
851 * @return true if the {@code SSLEngine} will not produce
852 * any more network data
853 *
854 * @see #closeOutbound()
855 * @see #closeInbound()
856 */
857 public abstract boolean isOutboundDone();
858
859
860 /**
861 * Returns the names of the cipher suites which could be enabled for use
862 * on this engine. Normally, only a subset of these will actually
863 * be enabled by default, since this list may include cipher suites which
864 * do not meet quality of service requirements for those defaults. Such
865 * cipher suites might be useful in specialized applications.
866 * <P>
867 * The returned array includes cipher suites from the list of standard
868 * cipher suite names in the <a href=
869 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
870 * JSSE Cipher Suite Names</a> section of the Java Cryptography
871 * Architecture Standard Algorithm Name Documentation, and may also
872 * include other cipher suites that the provider supports.
873 *
874 * @return an array of cipher suite names
875 * @see #getEnabledCipherSuites()
876 * @see #setEnabledCipherSuites(String [])
877 */
878 public abstract String [] getSupportedCipherSuites();
879
880
881 /**
882 * Returns the names of the SSL cipher suites which are currently
883 * enabled for use on this engine. When an SSLEngine is first
884 * created, all enabled cipher suites support a minimum quality of
885 * service. Thus, in some environments this value might be empty.
886 * <P>
887 * Note that even if a suite is enabled, it may never be used. This
888 * can occur if the peer does not support it, or its use is restricted,
889 * or the requisite certificates (and private keys) for the suite are
890 * not available, or an anonymous suite is enabled but authentication
891 * is required.
892 * <P>
893 * The returned array includes cipher suites from the list of standard
894 * cipher suite names in the <a href=
895 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
896 * JSSE Cipher Suite Names</a> section of the Java Cryptography
897 * Architecture Standard Algorithm Name Documentation, and may also
898 * include other cipher suites that the provider supports.
899 *
900 * @return an array of cipher suite names
901 * @see #getSupportedCipherSuites()
902 * @see #setEnabledCipherSuites(String [])
903 */
904 public abstract String [] getEnabledCipherSuites();
905
906
907 /**
908 * Sets the cipher suites enabled for use on this engine.
909 * <P>
910 * Each cipher suite in the {@code suites} parameter must have
911 * been listed by getSupportedCipherSuites(), or the method will
912 * fail. Following a successful call to this method, only suites
913 * listed in the {@code suites} parameter are enabled for use.
914 * <P>
915 * Note that the standard list of cipher suite names may be found in the
916 * <a href=
917 * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
918 * JSSE Cipher Suite Names</a> section of the Java Cryptography
919 * Architecture Standard Algorithm Name Documentation. Providers
920 * may support cipher suite names not found in this list or might not
921 * use the recommended name for a certain cipher suite.
922 * <P>
923 * See {@link #getEnabledCipherSuites()} for more information
924 * on why a specific cipher suite may never be used on a engine.
925 *
926 * @param suites Names of all the cipher suites to enable
927 * @throws IllegalArgumentException when one or more of the ciphers
928 * named by the parameter is not supported, or when the
929 * parameter is null.
930 * @see #getSupportedCipherSuites()
931 * @see #getEnabledCipherSuites()
932 */
933 public abstract void setEnabledCipherSuites(String suites []);
934
935
936 /**
937 * Returns the names of the protocols which could be enabled for use
938 * with this {@code SSLEngine}.
939 *
940 * @return an array of protocols supported
941 */
942 public abstract String [] getSupportedProtocols();
943
944
945 /**
946 * Returns the names of the protocol versions which are currently
947 * enabled for use with this {@code SSLEngine}.
948 * <P>
949 * Note that even if a protocol is enabled, it may never be used.
950 * This can occur if the peer does not support the protocol, or its
951 * use is restricted, or there are no enabled cipher suites supported
952 * by the protocol.
953 *
954 * @return an array of protocols
955 * @see #setEnabledProtocols(String [])
956 */
957 public abstract String [] getEnabledProtocols();
958
959
960 /**
961 * Set the protocol versions enabled for use on this engine.
962 * <P>
963 * The protocols must have been listed by getSupportedProtocols()
964 * as being supported. Following a successful call to this method,
965 * only protocols listed in the {@code protocols} parameter
966 * are enabled for use.
967 *
968 * @param protocols Names of all the protocols to enable.
969 * @throws IllegalArgumentException when one or more of
970 * the protocols named by the parameter is not supported or
971 * when the protocols parameter is null.
972 * @see #getEnabledProtocols()
973 */
974 public abstract void setEnabledProtocols(String protocols[]);
975
976
977 /**
978 * Returns the {@code SSLSession} in use in this
979 * {@code SSLEngine}.
980 * <P>
981 * These can be long lived, and frequently correspond to an entire
982 * login session for some user. The session specifies a particular
983 * cipher suite which is being actively used by all connections in
984 * that session, as well as the identities of the session's client
985 * and server.
986 * <P>
987 * Unlike {@link SSLSocket#getSession()}
988 * this method does not block until handshaking is complete.
989 * <P>
990 * Until the initial handshake has completed, this method returns
991 * a session object which reports an invalid cipher suite of
992 * "SSL_NULL_WITH_NULL_NULL".
993 *
994 * @return the {@code SSLSession} for this {@code SSLEngine}
995 * @see SSLSession
996 */
997 public abstract SSLSession getSession();
998
999
1000 /**
1001 * Returns the {@code SSLSession} being constructed during a SSL/TLS/DTLS
1002 * handshake.
1003 * <p>
1004 * TLS/DTLS protocols may negotiate parameters that are needed when using
1005 * an instance of this class, but before the {@code SSLSession} has
1006 * been completely initialized and made available via {@code getSession}.
1007 * For example, the list of valid signature algorithms may restrict
1008 * the type of certificates that can used during TrustManager
1009 * decisions, or the maximum TLS/DTLS fragment packet sizes can be
1010 * resized to better support the network environment.
1011 * <p>
1012 * This method provides early access to the {@code SSLSession} being
1013 * constructed. Depending on how far the handshake has progressed,
1014 * some data may not yet be available for use. For example, if a
1015 * remote server will be sending a Certificate chain, but that chain
1016 * has yet not been processed, the {@code getPeerCertificates}
1017 * method of {@code SSLSession} will throw a
1018 * SSLPeerUnverifiedException. Once that chain has been processed,
1019 * {@code getPeerCertificates} will return the proper value.
1020 *
1021 * @see SSLSocket
1022 * @see SSLSession
1023 * @see ExtendedSSLSession
1024 * @see X509ExtendedKeyManager
1025 * @see X509ExtendedTrustManager
1026 *
1027 * @return null if this instance is not currently handshaking, or
1028 * if the current handshake has not progressed far enough to
1029 * create a basic SSLSession. Otherwise, this method returns the
1030 * {@code SSLSession} currently being negotiated.
1031 * @throws UnsupportedOperationException if the underlying provider
1032 * does not implement the operation.
1033 *
1034 * @since 1.7
1035 */
1036 public SSLSession getHandshakeSession() {
1037 throw new UnsupportedOperationException();
1038 }
1039
1040
1041 /**
1042 * Initiates handshaking (initial or renegotiation) on this SSLEngine.
1043 * <P>
1044 * This method is not needed for the initial handshake, as the
1045 * {@code wrap()} and {@code unwrap()} methods will
1046 * implicitly call this method if handshaking has not already begun.
1047 * <P>
1048 * Note that the peer may also request a session renegotiation with
1049 * this {@code SSLEngine} by sending the appropriate
1050 * session renegotiate handshake message.
1051 * <P>
1052 * Unlike the {@link SSLSocket#startHandshake()
1053 * SSLSocket#startHandshake()} method, this method does not block
1054 * until handshaking is completed.
1055 * <P>
1056 * To force a complete SSL/TLS/DTLS session renegotiation, the current
1057 * session should be invalidated prior to calling this method.
1058 * <P>
1059 * Some protocols may not support multiple handshakes on an existing
1060 * engine and may throw an {@code SSLException}.
1061 *
1062 * @throws SSLException
1063 * if a problem was encountered while signaling the
1064 * {@code SSLEngine} to begin a new handshake.
1065 * See the class description for more information on
1066 * engine closure.
1067 * @throws IllegalStateException if the client/server mode
1068 * has not yet been set.
1069 * @see SSLSession#invalidate()
1070 */
1071 public abstract void beginHandshake() throws SSLException;
1072
1073
1074 /**
1075 * Returns the current handshake status for this {@code SSLEngine}.
1076 *
1077 * @return the current {@code SSLEngineResult.HandshakeStatus}.
1078 */
1079 public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus();
1080
1081
1082 /**
1083 * Configures the engine to use client (or server) mode when
1084 * handshaking.
1085 * <P>
1086 * This method must be called before any handshaking occurs.
1087 * Once handshaking has begun, the mode can not be reset for the
1088 * life of this engine.
1089 * <P>
1090 * Servers normally authenticate themselves, and clients
1091 * are not required to do so.
1092 *
1093 * @param mode true if the engine should start its handshaking
1094 * in "client" mode
1095 * @throws IllegalArgumentException if a mode change is attempted
1096 * after the initial handshake has begun.
1097 * @see #getUseClientMode()
1098 */
1099 public abstract void setUseClientMode(boolean mode);
1100
1101
1102 /**
1103 * Returns true if the engine is set to use client mode when
1104 * handshaking.
1105 *
1106 * @return true if the engine should do handshaking
1107 * in "client" mode
1108 * @see #setUseClientMode(boolean)
1109 */
1110 public abstract boolean getUseClientMode();
1111
1112
1113 /**
1114 * Configures the engine to <i>require</i> client authentication. This
1115 * option is only useful for engines in the server mode.
1116 * <P>
1117 * An engine's client authentication setting is one of the following:
1118 * <ul>
1119 * <li> client authentication required
1120 * <li> client authentication requested
1121 * <li> no client authentication desired
1122 * </ul>
1123 * <P>
1124 * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and
1125 * the client chooses not to provide authentication information
1126 * about itself, <i>the negotiations will stop and the engine will
1127 * begin its closure procedure</i>.
1128 * <P>
1129 * Calling this method overrides any previous setting made by
1130 * this method or {@link #setWantClientAuth(boolean)}.
1131 *
1132 * @param need set to true if client authentication is required,
1133 * or false if no client authentication is desired.
1134 * @see #getNeedClientAuth()
1135 * @see #setWantClientAuth(boolean)
1136 * @see #getWantClientAuth()
1137 * @see #setUseClientMode(boolean)
1138 */
1139 public abstract void setNeedClientAuth(boolean need);
1140
1141
1142 /**
1143 * Returns true if the engine will <i>require</i> client authentication.
1144 * This option is only useful to engines in the server mode.
1145 *
1146 * @return true if client authentication is required,
1147 * or false if no client authentication is desired.
1148 * @see #setNeedClientAuth(boolean)
1149 * @see #setWantClientAuth(boolean)
1150 * @see #getWantClientAuth()
1151 * @see #setUseClientMode(boolean)
1152 */
1153 public abstract boolean getNeedClientAuth();
1154
1155
1156 /**
1157 * Configures the engine to <i>request</i> client authentication.
1158 * This option is only useful for engines in the server mode.
1159 * <P>
1160 * An engine's client authentication setting is one of the following:
1161 * <ul>
1162 * <li> client authentication required
1163 * <li> client authentication requested
1164 * <li> no client authentication desired
1165 * </ul>
1166 * <P>
1167 * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and
1168 * the client chooses not to provide authentication information
1169 * about itself, <i>the negotiations will continue</i>.
1170 * <P>
1171 * Calling this method overrides any previous setting made by
1172 * this method or {@link #setNeedClientAuth(boolean)}.
1173 *
1174 * @param want set to true if client authentication is requested,
1175 * or false if no client authentication is desired.
1176 * @see #getWantClientAuth()
1177 * @see #setNeedClientAuth(boolean)
1178 * @see #getNeedClientAuth()
1179 * @see #setUseClientMode(boolean)
1180 */
1181 public abstract void setWantClientAuth(boolean want);
1182
1183
1184 /**
1185 * Returns true if the engine will <i>request</i> client authentication.
1186 * This option is only useful for engines in the server mode.
1187 *
1188 * @return true if client authentication is requested,
1189 * or false if no client authentication is desired.
1190 * @see #setNeedClientAuth(boolean)
1191 * @see #getNeedClientAuth()
1192 * @see #setWantClientAuth(boolean)
1193 * @see #setUseClientMode(boolean)
1194 */
1195 public abstract boolean getWantClientAuth();
1196
1197
1198 /**
1199 * Controls whether new SSL sessions may be established by this engine.
1200 * If session creations are not allowed, and there are no
1201 * existing sessions to resume, there will be no successful
1202 * handshaking.
1203 *
1204 * @param flag true indicates that sessions may be created; this
1205 * is the default. false indicates that an existing session
1206 * must be resumed
1207 * @see #getEnableSessionCreation()
1208 */
1209 public abstract void setEnableSessionCreation(boolean flag);
1210
1211
1212 /**
1213 * Returns true if new SSL sessions may be established by this engine.
1214 *
1215 * @return true indicates that sessions may be created; this
1216 * is the default. false indicates that an existing session
1217 * must be resumed
1218 * @see #setEnableSessionCreation(boolean)
1219 */
1220 public abstract boolean getEnableSessionCreation();
1221
1222 /**
1223 * Returns the SSLParameters in effect for this SSLEngine.
1224 * The ciphersuites and protocols of the returned SSLParameters
1225 * are always non-null.
1226 *
1227 * @return the SSLParameters in effect for this SSLEngine.
1228 * @since 1.6
1229 */
1230 public SSLParameters getSSLParameters() {
1231 SSLParameters params = new SSLParameters();
1232 params.setCipherSuites(getEnabledCipherSuites());
1233 params.setProtocols(getEnabledProtocols());
1234 if (getNeedClientAuth()) {
1235 params.setNeedClientAuth(true);
1236 } else if (getWantClientAuth()) {
1237 params.setWantClientAuth(true);
1238 }
1239 return params;
1240 }
1241
1242 /**
1243 * Applies SSLParameters to this engine.
1244 *
1245 * <p>This means:
1246 * <ul>
1247 * <li>If {@code params.getCipherSuites()} is non-null,
1248 * {@code setEnabledCipherSuites()} is called with that value.</li>
1249 * <li>If {@code params.getProtocols()} is non-null,
1250 * {@code setEnabledProtocols()} is called with that value.</li>
1251 * <li>If {@code params.getNeedClientAuth()} or
1252 * {@code params.getWantClientAuth()} return {@code true},
1253 * {@code setNeedClientAuth(true)} and
1254 * {@code setWantClientAuth(true)} are called, respectively;
1255 * otherwise {@code setWantClientAuth(false)} is called.</li>
1256 * <li>If {@code params.getServerNames()} is non-null, the engine will
1257 * configure its server names with that value.</li>
1258 * <li>If {@code params.getSNIMatchers()} is non-null, the engine will
1259 * configure its SNI matchers with that value.</li>
1260 * </ul>
1261 *
1262 * @param params the parameters
1263 * @throws IllegalArgumentException if the setEnabledCipherSuites() or
1264 * the setEnabledProtocols() call fails
1265 * @since 1.6
1266 */
1267 public void setSSLParameters(SSLParameters params) {
1268 String[] s;
1269 s = params.getCipherSuites();
1270 if (s != null) {
1271 setEnabledCipherSuites(s);
1272 }
1273 s = params.getProtocols();
1274 if (s != null) {
1275 setEnabledProtocols(s);
1276 }
1277 if (params.getNeedClientAuth()) {
1278 setNeedClientAuth(true);
1279 } else if (params.getWantClientAuth()) {
1280 setWantClientAuth(true);
1281 } else {
1282 setWantClientAuth(false);
1283 }
1284 }
1285
1286 /**
1287 * Returns the most recent application protocol value negotiated for this
1288 * connection.
1289 * <p>
1290 * If supported by the underlying SSL/TLS/DTLS implementation,
1291 * application name negotiation mechanisms such as <a
1292 * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 </a>, the
1293 * Application-Layer Protocol Negotiation (ALPN), can negotiate
1294 * application-level values between peers.
1295 * <p>
1296 * @implSpec
1297 * The implementation in this class throws
1298 * {@code UnsupportedOperationException} and performs no other action.
1299 *
1300 * @return null if it has not yet been determined if application
1301 * protocols might be used for this connection, an empty
1302 * {@code String} if application protocols values will not
1303 * be used, or a non-empty application protocol {@code String}
1304 * if a value was successfully negotiated.
1305 * @throws UnsupportedOperationException if the underlying provider
1306 * does not implement the operation.
1307 * @since 9
1308 */
1309 public String getApplicationProtocol() {
1310 throw new UnsupportedOperationException();
1311 }
1312
1313 /**
1314 * Returns the application protocol value negotiated on a SSL/TLS
1315 * handshake currently in progress.
1316 * <p>
1317 * Like {@link #getHandshakeSession()},
1318 * a connection may be in the middle of a handshake. The
1319 * application protocol may or may not yet be available.
1320 * <p>
1321 * @implSpec
1322 * The implementation in this class throws
1323 * {@code UnsupportedOperationException} and performs no other action.
1324 *
1325 * @return null if it has not yet been determined if application
1326 * protocols might be used for this handshake, an empty
1327 * {@code String} if application protocols values will not
1328 * be used, or a non-empty application protocol {@code String}
1329 * if a value was successfully negotiated.
1330 * @throws UnsupportedOperationException if the underlying provider
1331 * does not implement the operation.
1332 * @since 9
1333 */
1334 public String getHandshakeApplicationProtocol() {
1335 throw new UnsupportedOperationException();
1336 }
1337
1338 /**
1339 * Registers a callback function that selects an application protocol
1340 * value for a SSL/TLS/DTLS handshake.
1341 * The function overrides any values supplied using
1342 * {@link SSLParameters#setApplicationProtocols
1343 * SSLParameters.setApplicationProtocols} and it supports the following
1344 * type parameters:
1345 * <blockquote>
1346 * <dl>
1347 * <dt> {@code SSLEngine}
1348 * <dd> The function's first argument allows the current {@code SSLEngine}
1349 * to be inspected, including the handshake session and configuration
1350 * settings.
1351 * <dt> {@code List<String>}
1352 * <dd> The function's second argument lists the application protocol names
1353 * advertised by the TLS peer.
1354 * <dt> {@code String}
1355 * <dd> The function's result is an application protocol name, or null to
1356 * indicate that none of the advertised names are acceptable.
1357 * If the return value is an empty {@code String} then application
1358 * protocol indications will not be used.
1359 * If the return value is null (no value chosen) or is a value that
1360 * was not advertised by the peer, the underlying protocol will
1361 * determine what action to take. (For example, ALPN will send a
1362 * "no_application_protocol" alert and terminate the connection.)
1363 * </dl>
1364 * </blockquote>
1365 *
1366 * For example, the following call registers a callback function that
1367 * examines the TLS handshake parameters and selects an application protocol
1368 * name:
1369 * <pre>{@code
1370 * serverEngine.setHandshakeApplicationProtocolSelector(
1371 * (serverEngine, clientProtocols) -> {
1372 * SSLSession session = serverEngine.getHandshakeSession();
1373 * return chooseApplicationProtocol(
1374 * serverEngine,
1375 * clientProtocols,
1376 * session.getProtocol(),
1377 * session.getCipherSuite());
1378 * });
1379 * }</pre>
1380 *
1381 * @apiNote
1382 * This method should be called by TLS server applications before the TLS
1383 * handshake begins. Also, this {@code SSLEngine} should be configured with
1384 * parameters that are compatible with the application protocol selected by
1385 * the callback function. For example, enabling a poor choice of cipher
1386 * suites could result in no suitable application protocol.
1387 * See {@link SSLParameters}.
1388 *
1389 * @implSpec
1390 * The implementation in this class throws
1391 * {@code UnsupportedOperationException} and performs no other action.
1392 *
1393 * @param selector the callback function, or null to disable the callback
1394 * functionality.
1395 * @throws UnsupportedOperationException if the underlying provider
1396 * does not implement the operation.
1397 * @since 9
1398 */
1399 public void setHandshakeApplicationProtocolSelector(
1400 BiFunction<SSLEngine, List<String>, String> selector) {
1401 throw new UnsupportedOperationException();
1402 }
1403
1404 /**
1405 * Retrieves the callback function that selects an application protocol
1406 * value during a SSL/TLS/DTLS handshake.
1407 * See {@link #setHandshakeApplicationProtocolSelector
1408 * setHandshakeApplicationProtocolSelector}
1409 * for the function's type parameters.
1410 *
1411 * @implSpec
1412 * The implementation in this class throws
1413 * {@code UnsupportedOperationException} and performs no other action.
1414 *
1415 * @return the callback function, or null if none has been set.
1416 * @throws UnsupportedOperationException if the underlying provider
1417 * does not implement the operation.
1418 * @since 9
1419 */
1420 public BiFunction<SSLEngine, List<String>, String>
1421 getHandshakeApplicationProtocolSelector() {
1422 throw new UnsupportedOperationException();
1423 }
1424 }