KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > net > ssl > SSLEngine


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