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