3002N/A * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * A class which enables secure communications using protocols such as 0N/A * the Secure Sockets Layer (SSL) or 0N/A * Layer Security" (TLS) </A> protocols, but is transport independent. 0N/A * The secure communications modes include: <UL> 0N/A * <LI> <em>Integrity Protection</em>. SSL/TLS protects against 0N/A * modification of messages by an active wiretapper. 0N/A * <LI> <em>Authentication</em>. In most modes, SSL/TLS provides 0N/A * peer authentication. Servers are usually authenticated, and 0N/A * clients may be authenticated as requested by servers. 0N/A * <LI> <em>Confidentiality (Privacy Protection)</em>. In most 0N/A * modes, SSL/TLS encrypts data being sent between client and 0N/A * server. This protects the confidentiality of data, so that 0N/A * passive wiretappers won't see sensitive data such as financial 0N/A * information or personal information of many kinds. 0N/A * These kinds of protection are specified by a "cipher suite", which 0N/A * is a combination of cryptographic algorithms used by a given SSL 0N/A * connection. During the negotiation process, the two endpoints must 0N/A * agree on a cipher suite that is available in both environments. If 0N/A * there is no such suite in common, no SSL connection can be 0N/A * established, and no data can be exchanged. 0N/A * The cipher suite used is established by a negotiation process called 0N/A * "handshaking". The goal of this process is to create or rejoin a 0N/A * "session", which may protect many connections over time. After 0N/A * handshaking has completed, you can access session attributes by 0N/A * using the {@link #getSession()} method. 0N/A * The <code>SSLSocket</code> class provides much of the same security 0N/A * functionality, but all of the inbound and outbound data is 0N/A * automatically transported using the underlying {@link 0N/A * java.net.Socket Socket}, which by design uses a blocking model. 0N/A * While this is appropriate for many applications, this model does not 0N/A * provide the scalability required by large servers. 0N/A * The primary distinction of an <code>SSLEngine</code> is that it 0N/A * operates on inbound and outbound byte streams, independent of the 0N/A * transport mechanism. It is the responsibility of the 0N/A * <code>SSLEngine</code> user to arrange for reliable I/O transport to 0N/A * the peer. By separating the SSL/TLS abstraction from the I/O 0N/A * transport mechanism, the <code>SSLEngine</code> can be used for a 0N/A * wide variety of I/O types, such as {@link 0N/A * java.nio.channels.spi.AbstractSelectableChannel#configureBlocking(boolean) 0N/A * non-blocking I/O (polling)}, {@link java.nio.channels.Selector 0N/A * selectable non-blocking I/O}, {@link java.net.Socket Socket} and the 0N/A * ByteBuffers} or byte arrays, <A 0N/A * I/O models </A>, and so on. 0N/A * At a high level, the <code>SSLEngine</code> appears thus: 0N/A * +----+-----|-----+----+ 0N/A * wrap() | | | unwrap() 0N/A * | OUTBOUND | INBOUND | 0N/A * +----+-----|-----+----+ 0N/A * Application data (also known as plaintext or cleartext) is data which 0N/A * is produced or consumed by an application. Its counterpart is 0N/A * network data, which consists of either handshaking and/or ciphertext 0N/A * (encrypted) data, and destined to be transported via an I/O 0N/A * mechanism. Inbound data is data which has been received from the 0N/A * peer, and outbound data is destined for the peer. 0N/A * (In the context of an <code>SSLEngine</code>, the term "handshake 0N/A * data" is taken to mean any data exchanged to establish and control a 0N/A * secure connection. Handshake data includes the SSL/TLS messages 0N/A * "alert", "change_cipher_spec," and "handshake.") 0N/A * There are five distinct phases to an <code>SSLEngine</code>. 0N/A * <li> Creation - The <code>SSLEngine</code> has been created and 0N/A * initialized, but has not yet been used. During this phase, an 0N/A * application may set any <code>SSLEngine</code>-specific settings 0N/A * (enabled cipher suites, whether the <code>SSLEngine</code> should 0N/A * handshake in client or server mode, and so on). Once 0N/A * handshaking has begun, though, any new settings (except 0N/A * the next handshake. 0N/A * <li> Initial Handshake - The initial handshake is a procedure by 0N/A * which the two peers exchange communication parameters until an 0N/A * SSLSession is established. Application data can not be sent during 0N/A * <li> Application Data - Once the communication parameters have 0N/A * been established and the handshake is complete, application data 0N/A * may flow through the <code>SSLEngine</code>. Outbound 0N/A * application messages are encrypted and integrity protected, 0N/A * and inbound messages reverse the process. 0N/A * <li> Rehandshaking - Either side may request a renegotiation of 0N/A * the session at any time during the Application Data phase. New 0N/A * handshaking data can be intermixed among the application data. 0N/A * Before starting the rehandshake phase, the application may 0N/A * reset the SSL/TLS communication parameters such as the list of 0N/A * enabled ciphersuites and whether to use client authentication, 0N/A * handshaking has begun, any new <code>SSLEngine</code> 0N/A * configuration settings will not be used until the next 0N/A * <li> Closure - When the connection is no longer needed, the 0N/A * application should close the <code>SSLEngine</code> and should 0N/A * closing the underlying transport mechanism. Once an engine is 0N/A * closed, it is not reusable: a new <code>SSLEngine</code> must 0N/A * An <code>SSLEngine</code> is created by calling {@link 0N/A * SSLContext#createSSLEngine()} from an initialized 0N/A * <code>SSLContext</code>. Any configuration 0N/A * parameters should be set before making the first call to 0N/A * <code>wrap()</code>, <code>unwrap()</code>, or 0N/A * <code>beginHandshake()</code>. These methods all trigger the 0N/A * initial handshake. 0N/A * Data moves through the engine by calling {@link #wrap(ByteBuffer, 0N/A * ByteBuffer) wrap()} or {@link #unwrap(ByteBuffer, ByteBuffer) 0N/A * unwrap()} on outbound or inbound data, respectively. Depending on 0N/A * the state of the <code>SSLEngine</code>, a <code>wrap()</code> call 0N/A * may consume application data from the source buffer and may produce 0N/A * network data in the destination buffer. The outbound data 0N/A * may contain application and/or handshake data. A call to 0N/A * <code>unwrap()</code> will examine the source buffer and may 0N/A * advance the handshake if the data is handshaking information, or 0N/A * may place application data in the destination buffer if the data 0N/A * is application. The state of the underlying SSL/TLS algorithm 0N/A * will determine when data is consumed and produced. 0N/A * Calls to <code>wrap()</code> and <code>unwrap()</code> return an 0N/A * <code>SSLEngineResult</code> which indicates the status of the 0N/A * operation, and (optionally) how to interact with the engine to make 0N/A * packets only, and does not store application data internally between 0N/A * calls to <code>wrap()/unwrap()</code>. Thus input and output 0N/A * <code>ByteBuffer</code>s must be sized appropriately to hold the 0N/A * maximum record that can be produced. Calls to {@link 0N/A * SSLSession#getPacketBufferSize()} and {@link 0N/A * SSLSession#getApplicationBufferSize()} should be used to determine 0N/A * the appropriate buffer sizes. The size of the outbound application 0N/A * data buffer generally does not matter. If buffer conditions do not 0N/A * must determine (via {@link SSLEngineResult}) and correct the 0N/A * problem, and then try the call again. 0N/A * For example, <code>unwrap()</code> will return a {@link 0N/A * SSLEngineResult.Status#BUFFER_OVERFLOW} result if the engine 0N/A * determines that there is not enough destination buffer space available. 0N/A * Applications should call {@link SSLSession#getApplicationBufferSize()} 0N/A * and compare that value with the space available in the destination buffer, 0N/A * enlarging the buffer if necessary. Similarly, if <code>unwrap()</code> 0N/A * were to return a {@link SSLEngineResult.Status#BUFFER_UNDERFLOW}, the 0N/A * application should call {@link SSLSession#getPacketBufferSize()} to ensure 0N/A * that the source buffer has enough room to hold a record (enlarging if 0N/A * necessary), and then obtain more inbound data. 0N/A * SSLEngineResult r = engine.unwrap(src, dst); 0N/A * switch (r.getStatus()) { 0N/A * // Could attempt to drain the dst buffer of any already obtained 0N/A * // data, but we'll just increase it to the size needed. 0N/A * int appSize = engine.getSession().getApplicationBufferSize(); 0N/A * ByteBuffer b = ByteBuffer.allocate(appSize + dst.position()); 0N/A * // retry the operation. 0N/A * int netSize = engine.getSession().getPacketBufferSize(); 0N/A * // Resize buffer if needed. 0N/A * if (netSize > dst.capacity()) { 0N/A * ByteBuffer b = ByteBuffer.allocate(netSize); 0N/A * // Obtain more inbound network data for src, 0N/A * // then retry the operation. 0N/A * // other cases: CLOSED, OK. 0N/A * Unlike <code>SSLSocket</code>, all methods of SSLEngine are 0N/A * non-blocking. <code>SSLEngine</code> implementations may 0N/A * require the results of tasks that may take an extended period of 0N/A * time to complete, or may even block. For example, a TrustManager 0N/A * may need to connect to a remote certificate validation service, 0N/A * or a KeyManager might need to prompt a user to determine which 0N/A * certificate to use as part of client authentication. Additionally, 0N/A * creating cryptographic signatures and verifying them can be slow, 0N/A * seemingly blocking. 0N/A * For any operation which may potentially block, the 0N/A * <code>SSLEngine</code> will create a {@link java.lang.Runnable} 0N/A * delegated task. When <code>SSLEngineResult</code> indicates that a 0N/A * delegated task result is needed, the application must call {@link 0N/A * #getDelegatedTask()} to obtain an outstanding delegated task and 0N/A * call its {@link java.lang.Runnable#run() run()} method (possibly using 0N/A * a different thread depending on the compute strategy). The 0N/A * application should continue obtaining delegated tasks until no more 0N/A * exist, and try the original operation again. 0N/A * At the end of a communication session, applications should properly 0N/A * messages, and these messages should be communicated to the peer 0N/A * before releasing the <code>SSLEngine</code> and closing the 0N/A * underlying transport mechanism. A close can be initiated by one of: 0N/A * an SSLException, an inbound closure handshake message, or one of the 0N/A * close methods. In all cases, closure handshake messages are 0N/A * generated by the engine, and <code>wrap()</code> should be repeatedly 0N/A * called until the resulting <code>SSLEngineResult</code>'s status 0N/A * returns "CLOSED", or {@link #isOutboundDone()} returns true. All 0N/A * data obtained from the <code>wrap()</code> method should be sent to the 0N/A * {@link #closeOutbound()} is used to signal the engine that the 0N/A * application will not be sending any more data. 0N/A * A peer will signal its intent to close by sending its own closure 0N/A * handshake message. After this message has been received and 0N/A * processed by the local <code>SSLEngine</code>'s <code>unwrap()</code> 0N/A * call, the application can detect the close by calling 0N/A * <code>unwrap()</code> and looking for a <code>SSLEngineResult</code> 0N/A * with status "CLOSED", or if {@link #isInboundDone()} returns true. 0N/A * If for some reason the peer closes the communication link without 0N/A * sending the proper SSL/TLS closure message, the application can 0N/A * detect the end-of-stream and can signal the engine via {@link 0N/A * #closeInbound()} that there will no more inbound messages to 0N/A * process. Some applications might choose to require orderly shutdown 0N/A * messages from a peer, in which case they can check that the closure 0N/A * was generated by a handshake message and not by an end-of-stream 0N/A * There are two groups of cipher suites which you will need to know 0N/A * about when managing cipher suites: 0N/A * <LI> <em>Supported</em> cipher suites: all the suites which are 0N/A * supported by the SSL implementation. This list is reported 0N/A * using {@link #getSupportedCipherSuites()}. 0N/A * <LI> <em>Enabled</em> cipher suites, which may be fewer than 0N/A * the full set of supported suites. This group is set using the 0N/A * {@link #setEnabledCipherSuites(String [])} method, and 0N/A * queried using the {@link #getEnabledCipherSuites()} method. 0N/A * Initially, a default set of cipher suites will be enabled on a 0N/A * new engine that represents the minimum suggested 0N/A * Implementation defaults require that only cipher suites which 0N/A * authenticate servers and provide confidentiality be enabled by 0N/A * default. Only if both sides explicitly agree to unauthenticated 0N/A * and/or non-private (unencrypted) communications will such a 0N/A * cipher suite be selected. 0N/A * Each SSL/TLS connection must have one client and one server, thus 0N/A * each endpoint must decide which role to assume. This choice determines 0N/A * who begins the handshaking process as well as which type of messages 0N/A * should be sent by each party. The method {@link 0N/A * #setUseClientMode(boolean)} configures the mode. Once the initial 0N/A * handshaking has started, an <code>SSLEngine</code> can not switch 0N/A * between client and server modes, even when performing renegotiations. 0N/A * Applications might choose to process delegated tasks in different 0N/A * threads. When an <code>SSLEngine</code> 0N/A * is created, the current {@link java.security.AccessControlContext} 0N/A * is saved. All future delegated tasks will be processed using this 0N/A * context: that is, all access control decisions will be made using the 0N/A * context captured at engine creation. 0N/A * <B>Concurrency Notes</B>: 0N/A * There are two concurrency issues to be aware of: 0N/A * <li>The <code>wrap()</code> and <code>unwrap()</code> methods 0N/A * may execute concurrently of each other. 0N/A * <li> The SSL/TLS protocols employ ordered packets. 0N/A * Applications must take care to ensure that generated packets 0N/A * are delivered in sequence. If packets arrive 0N/A * out-of-order, unexpected or fatal results may occur. 0N/A * synchronized (outboundLock) { 0N/A * sslEngine.wrap(src, dst); 0N/A * outboundQueue.put(dst); 0N/A * As a corollary, two threads must not attempt to call the same method 0N/A * (either <code>wrap()</code> or <code>unwrap()</code>) concurrently, 0N/A * because there is no way to guarantee the eventual packet ordering. 0N/A * @see SSLServerSocket 0N/A * @see java.net.Socket 0N/A * @author Brad R. Wetmore 0N/A * Constructor for an <code>SSLEngine</code> providing no hints 0N/A * for an internal session reuse strategy. 0N/A * @see SSLContext#createSSLEngine() 0N/A * @see SSLSessionContext 0N/A * Constructor for an <code>SSLEngine</code>. 0N/A * <code>SSLEngine</code> implementations may use the 0N/A * <code>peerHost</code> and <code>peerPort</code> parameters as hints 0N/A * for their internal session reuse strategy. 0N/A * Some cipher suites (such as Kerberos) require remote hostname 0N/A * information. Implementations of this class should use this 0N/A * constructor to use Kerberos. 0N/A * The parameters are not authenticated by the 0N/A * <code>SSLEngine</code>. 0N/A * @param peerHost the name of the peer host 0N/A * @param peerPort the port number of the peer 0N/A * @see SSLContext#createSSLEngine(String, int) 0N/A * @see SSLSessionContext 0N/A * Returns the host name of the peer. 0N/A * Note that the value is not authenticated, and should not be 0N/A * @return the host name of the peer, or null if nothing is 0N/A * Returns the port number of the peer. 0N/A * Note that the value is not authenticated, and should not be 0N/A * @return the port number of the peer, or -1 if nothing is 0N/A * Attempts to encode a buffer of plaintext application data into 0N/A * An invocation of this method behaves in exactly the same manner 0N/A * as the invocation: 0N/A * {@link #wrap(ByteBuffer [], int, int, ByteBuffer) 0N/A * engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);} 0N/A * </pre</blockquote> 0N/A * a <code>ByteBuffer</code> containing outbound application data 0N/A * a <code>ByteBuffer</code> to hold outbound network data 0N/A * @return an <code>SSLEngineResult</code> describing the result 0N/A * of this operation. 0N/A * @throws SSLException 0N/A * A problem was encountered while processing the 0N/A * data that caused the <code>SSLEngine</code> to abort. 0N/A * See the class description for more information on 0N/A * @throws ReadOnlyBufferException 0N/A * if the <code>dst</code> buffer is read-only. 0N/A * @throws IllegalArgumentException 0N/A * if either <code>src</code> or <code>dst</code> 0N/A * has not yet been set. 0N/A * @see #wrap(ByteBuffer [], int, int, ByteBuffer) 0N/A * Attempts to encode plaintext bytes from a sequence of data 0N/A * An invocation of this method behaves in exactly the same manner 0N/A * as the invocation: 0N/A * {@link #wrap(ByteBuffer [], int, int, ByteBuffer) 0N/A * engine.wrap(srcs, 0, srcs.length, dst);} 0N/A * </pre</blockquote> 0N/A * an array of <code>ByteBuffers</code> containing the 0N/A * outbound application data 0N/A * a <code>ByteBuffer</code> to hold outbound network data 0N/A * @return an <code>SSLEngineResult</code> describing the result 0N/A * of this operation. 0N/A * @throws SSLException 0N/A * A problem was encountered while processing the 0N/A * data that caused the <code>SSLEngine</code> to abort. 0N/A * See the class description for more information on 0N/A * @throws ReadOnlyBufferException 0N/A * if the <code>dst</code> buffer is read-only. 0N/A * @throws IllegalArgumentException 0N/A * if either <code>srcs</code> or <code>dst</code> 0N/A * is null, or if any element in <code>srcs</code> is null. 0N/A * has not yet been set. 0N/A * @see #wrap(ByteBuffer [], int, int, ByteBuffer) 0N/A * Attempts to encode plaintext bytes from a subsequence of data 0N/A * buffers into SSL/TLS network data. This <i>"gathering"</i> 0N/A * operation encodes, in a single invocation, a sequence of bytes 0N/A * from one or more of a given sequence of buffers. Gathering 0N/A * wraps are often useful when implementing network protocols or 0N/A * file formats that, for example, group data into segments 0N/A * consisting of one or more fixed-length headers followed by a 0N/A * variable-length body. See 0N/A * {@link java.nio.channels.GatheringByteChannel} for more 0N/A * information on gathering, and {@link 0N/A * java.nio.channels.GatheringByteChannel#write(ByteBuffer[], 0N/A * int, int)} for more information on the subsequence 0N/A * Depending on the state of the SSLEngine, this method may produce 0N/A * network data without consuming any application data (for example, 0N/A * it may generate handshake data.) 0N/A * The application is responsible for reliably transporting the 0N/A * network data to the peer, and for ensuring that data created by 0N/A * multiple calls to wrap() is transported in the same order in which 0N/A * it was generated. The application must properly synchronize 0N/A * multiple calls to this method. 0N/A * If this <code>SSLEngine</code> has not yet started its initial 0N/A * handshake, this method will automatically start the handshake. 0N/A * This method will attempt to produce one SSL/TLS packet, and will 0N/A * consume as much source data as possible, but will never consume 0N/A * more than the sum of the bytes remaining in each buffer. Each 0N/A * <code>ByteBuffer</code>'s position is updated to reflect the 0N/A * amount of data consumed or produced. The limits remain the 0N/A * The underlying memory used by the <code>srcs</code> and 0N/A * <code>dst ByteBuffer</code>s must not be the same. 0N/A * See the class description for more information on engine closure. 0N/A * an array of <code>ByteBuffers</code> containing the 0N/A * outbound application data 0N/A * The offset within the buffer array of the first buffer from 0N/A * which bytes are to be retrieved; it must be non-negative 0N/A * and no larger than <code>srcs.length</code> 0N/A * The maximum number of buffers to be accessed; it must be 0N/A * non-negative and no larger than 0N/A * <code>srcs.length</code> - <code>offset</code> 0N/A * a <code>ByteBuffer</code> to hold outbound network data 0N/A * @return an <code>SSLEngineResult</code> describing the result 0N/A * of this operation. 0N/A * @throws SSLException 0N/A * A problem was encountered while processing the 0N/A * data that caused the <code>SSLEngine</code> to abort. 0N/A * See the class description for more information on 0N/A * @throws IndexOutOfBoundsException 0N/A * if the preconditions on the <code>offset</code> and 0N/A * <code>length</code> parameters do not hold. 0N/A * @throws ReadOnlyBufferException 0N/A * if the <code>dst</code> buffer is read-only. 0N/A * @throws IllegalArgumentException 0N/A * if either <code>srcs</code> or <code>dst</code> 0N/A * is null, or if any element in the <code>srcs</code> 0N/A * subsequence specified is null. 0N/A * has not yet been set. 0N/A * @see java.nio.channels.GatheringByteChannel 0N/A * @see java.nio.channels.GatheringByteChannel#write( 0N/A * ByteBuffer[], int, int) 0N/A * Attempts to decode SSL/TLS network data into a plaintext 0N/A * application data buffer. 0N/A * An invocation of this method behaves in exactly the same manner 0N/A * as the invocation: 0N/A * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int) 0N/A * engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);} 0N/A * </pre</blockquote> 0N/A * a <code>ByteBuffer</code> containing inbound network data. 0N/A * a <code>ByteBuffer</code> to hold inbound application data. 0N/A * @return an <code>SSLEngineResult</code> describing the result 0N/A * of this operation. 0N/A * @throws SSLException 0N/A * A problem was encountered while processing the 0N/A * data that caused the <code>SSLEngine</code> to abort. 0N/A * See the class description for more information on 0N/A * @throws ReadOnlyBufferException 0N/A * if the <code>dst</code> buffer is read-only. 0N/A * @throws IllegalArgumentException 0N/A * if either <code>src</code> or <code>dst</code> 0N/A * has not yet been set. 0N/A * @see #unwrap(ByteBuffer, ByteBuffer [], int, int) 0N/A * Attempts to decode SSL/TLS network data into a sequence of plaintext 0N/A * application data buffers. 0N/A * An invocation of this method behaves in exactly the same manner 0N/A * as the invocation: 0N/A * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int) 0N/A * engine.unwrap(src, dsts, 0, dsts.length);} 0N/A * </pre</blockquote> 0N/A * a <code>ByteBuffer</code> containing inbound network data. 0N/A * an array of <code>ByteBuffer</code>s to hold inbound 0N/A * @return an <code>SSLEngineResult</code> describing the result 0N/A * of this operation. 0N/A * @throws SSLException 0N/A * A problem was encountered while processing the 0N/A * data that caused the <code>SSLEngine</code> to abort. 0N/A * See the class description for more information on 0N/A * @throws ReadOnlyBufferException 0N/A * if any of the <code>dst</code> buffers are read-only. 0N/A * @throws IllegalArgumentException 0N/A * if either <code>src</code> or <code>dsts</code> 0N/A * is null, or if any element in <code>dsts</code> is null. 0N/A * has not yet been set. 0N/A * @see #unwrap(ByteBuffer, ByteBuffer [], int, int) 0N/A * Attempts to decode SSL/TLS network data into a subsequence of 0N/A * plaintext application data buffers. This <i>"scattering"</i> 0N/A * operation decodes, in a single invocation, a sequence of bytes 0N/A * into one or more of a given sequence of buffers. Scattering 0N/A * unwraps are often useful when implementing network protocols or 0N/A * file formats that, for example, group data into segments 0N/A * consisting of one or more fixed-length headers followed by a 0N/A * variable-length body. See 0N/A * {@link java.nio.channels.ScatteringByteChannel} for more 0N/A * information on scattering, and {@link 0N/A * java.nio.channels.ScatteringByteChannel#read(ByteBuffer[], 0N/A * int, int)} for more information on the subsequence 0N/A * Depending on the state of the SSLEngine, this method may consume 0N/A * network data without producing any application data (for example, 0N/A * it may consume handshake data.) 0N/A * The application is responsible for reliably obtaining the network 0N/A * data from the peer, and for invoking unwrap() on the data in the 0N/A * order it was received. The application must properly synchronize 0N/A * multiple calls to this method. 0N/A * If this <code>SSLEngine</code> has not yet started its initial 0N/A * handshake, this method will automatically start the handshake. 0N/A * This method will attempt to consume one complete SSL/TLS network 0N/A * packet, but will never consume more than the sum of the bytes 0N/A * remaining in the buffers. Each <code>ByteBuffer</code>'s 0N/A * position is updated to reflect the amount of data consumed or 0N/A * produced. The limits remain the same. 0N/A * The underlying memory used by the <code>src</code> and 0N/A * <code>dsts ByteBuffer</code>s must not be the same. 0N/A * The inbound network buffer may be modified as a result of this 0N/A * call: therefore if the network data packet is required for some 0N/A * secondary purpose, the data should be duplicated before calling this 0N/A * method. Note: the network data will not be useful to a second 0N/A * SSLEngine, as each SSLEngine contains unique random state which 0N/A * See the class description for more information on engine closure. 0N/A * a <code>ByteBuffer</code> containing inbound network data. 0N/A * an array of <code>ByteBuffer</code>s to hold inbound 0N/A * The offset within the buffer array of the first buffer from 0N/A * which bytes are to be transferred; it must be non-negative 0N/A * and no larger than <code>dsts.length</code>. 0N/A * The maximum number of buffers to be accessed; it must be 0N/A * non-negative and no larger than 0N/A * <code>dsts.length</code> - <code>offset</code>. 0N/A * @return an <code>SSLEngineResult</code> describing the result 0N/A * of this operation. 0N/A * @throws SSLException 0N/A * A problem was encountered while processing the 0N/A * data that caused the <code>SSLEngine</code> to abort. 0N/A * See the class description for more information on 0N/A * @throws IndexOutOfBoundsException 0N/A * If the preconditions on the <code>offset</code> and 0N/A * <code>length</code> parameters do not hold. 0N/A * @throws ReadOnlyBufferException 0N/A * if any of the <code>dst</code> buffers are read-only. 0N/A * @throws IllegalArgumentException 0N/A * if either <code>src</code> or <code>dsts</code> 0N/A * is null, or if any element in the <code>dsts</code> 0N/A * subsequence specified is null. 0N/A * has not yet been set. 0N/A * @see java.nio.channels.ScatteringByteChannel 0N/A * @see java.nio.channels.ScatteringByteChannel#read( 0N/A * ByteBuffer[], int, int) 0N/A * Returns a delegated <code>Runnable</code> task for 0N/A * this <code>SSLEngine</code>. 0N/A * <code>SSLEngine</code> operations may require the results of 0N/A * operations that block, or may take an extended period of time to 0N/A * complete. This method is used to obtain an outstanding {@link 0N/A * java.lang.Runnable} operation (task). Each task must be assigned 0N/A * a thread (possibly the current) to perform the {@link 0N/A * java.lang.Runnable#run() run} operation. Once the 0N/A * <code>run</code> method returns, the <code>Runnable</code> object 0N/A * is no longer needed and may be discarded. 0N/A * Delegated tasks run in the <code>AccessControlContext</code> 0N/A * in place when this object was created. 0N/A * A call to this method will return each outstanding task 0N/A * Multiple delegated tasks can be run in parallel. 0N/A * @return a delegated <code>Runnable</code> task, or null 0N/A * if none are available. 0N/A * Signals that no more inbound network data will be sent 0N/A * to this <code>SSLEngine</code>. 0N/A * If the application initiated the closing process by calling 0N/A * {@link #closeOutbound()}, under some circumstances it is not 0N/A * required that the initiator wait for the peer's corresponding 0N/A * close message. (See section 7.2.1 of the TLS specification (<A 0N/A * information on waiting for closure alerts.) In such cases, this 0N/A * method need not be called. 0N/A * But if the application did not initiate the closure process, or 0N/A * if the circumstances above do not apply, this method should be 0N/A * called whenever the end of the SSL/TLS data stream is reached. 0N/A * This ensures closure of the inbound side, and checks that the 0N/A * peer followed the SSL/TLS close procedure properly, thus 0N/A * detecting possible truncation attacks. 0N/A * This method is idempotent: if the inbound side has already 0N/A * been closed, this method does not do anything. 0N/A * {@link #wrap(ByteBuffer, ByteBuffer) wrap()} should be 0N/A * called to flush any remaining handshake data. 0N/A * @throws SSLException 0N/A * if this engine has not received the proper SSL/TLS close 0N/A * notification message from the peer. 0N/A * @see #isInboundDone() 0N/A * @see #isOutboundDone() 0N/A * Returns whether {@link #unwrap(ByteBuffer, ByteBuffer)} will 0N/A * accept any more inbound data messages. 0N/A * @return true if the <code>SSLEngine</code> will not 0N/A * consume anymore network data (and by implication, 0N/A * will not produce any more application data.) 0N/A * @see #closeInbound() 0N/A * Signals that no more outbound application data will be sent 0N/A * on this <code>SSLEngine</code>. 0N/A * This method is idempotent: if the outbound side has already 0N/A * been closed, this method does not do anything. 0N/A * {@link #wrap(ByteBuffer, ByteBuffer)} should be 0N/A * called to flush any remaining handshake data. 0N/A * @see #isOutboundDone() 0N/A * Returns whether {@link #wrap(ByteBuffer, ByteBuffer)} will 0N/A * produce any more outbound data messages. 0N/A * Note that during the closure phase, a <code>SSLEngine</code> may 0N/A * generate handshake closure data that must be sent to the peer. 0N/A * <code>wrap()</code> must be called to generate this data. When 0N/A * this method returns true, no more outbound data will be created. 0N/A * @return true if the <code>SSLEngine</code> will not produce 0N/A * any more network data 0N/A * @see #closeOutbound() 0N/A * @see #closeInbound() 0N/A * Returns the names of the cipher suites which could be enabled for use 0N/A * on this engine. Normally, only a subset of these will actually 0N/A * be enabled by default, since this list may include cipher suites which 0N/A * do not meet quality of service requirements for those defaults. Such 0N/A * cipher suites might be useful in specialized applications. 0N/A * @return an array of cipher suite names 0N/A * @see #getEnabledCipherSuites() 0N/A * @see #setEnabledCipherSuites(String []) 0N/A * Returns the names of the SSL cipher suites which are currently 0N/A * enabled for use on this engine. When an SSLEngine is first 0N/A * created, all enabled cipher suites support a minimum quality of 0N/A * service. Thus, in some environments this value might be empty. 0N/A * Even if a suite has been enabled, it might never be used. (For 0N/A * example, the peer does not support it, the requisite 0N/A * anonymous suite is enabled but authentication is required.) 0N/A * @return an array of cipher suite names 0N/A * @see #getSupportedCipherSuites() 0N/A * @see #setEnabledCipherSuites(String []) 0N/A * Sets the cipher suites enabled for use on this engine. 0N/A * Each cipher suite in the <code>suites</code> parameter must have 0N/A * been listed by getSupportedCipherSuites(), or the method will 0N/A * fail. Following a successful call to this method, only suites 0N/A * listed in the <code>suites</code> parameter are enabled for use. 0N/A * See {@link #getEnabledCipherSuites()} for more information 0N/A * on why a specific cipher suite may never be used on a engine. 0N/A * @param suites Names of all the cipher suites to enable 0N/A * @throws IllegalArgumentException when one or more of the ciphers 0N/A * named by the parameter is not supported, or when the 0N/A * parameter is null. 0N/A * @see #getSupportedCipherSuites() 0N/A * @see #getEnabledCipherSuites() 0N/A * Returns the names of the protocols which could be enabled for use 0N/A * with this <code>SSLEngine</code>. 0N/A * @return an array of protocols supported 0N/A * Returns the names of the protocol versions which are currently 0N/A * enabled for use with this <code>SSLEngine</code>. 0N/A * @return an array of protocols 0N/A * @see #setEnabledProtocols(String []) 0N/A * Set the protocol versions enabled for use on this engine. 0N/A * The protocols must have been listed by getSupportedProtocols() 0N/A * as being supported. Following a successful call to this method, 0N/A * only protocols listed in the <code>protocols</code> parameter 0N/A * are enabled for use. 0N/A * @param protocols Names of all the protocols to enable. 0N/A * @throws IllegalArgumentException when one or more of 0N/A * the protocols named by the parameter is not supported or 0N/A * when the protocols parameter is null. 0N/A * @see #getEnabledProtocols() 0N/A * Returns the <code>SSLSession</code> in use in this 0N/A * <code>SSLEngine</code>. 0N/A * These can be long lived, and frequently correspond to an entire 0N/A * login session for some user. The session specifies a particular 0N/A * cipher suite which is being actively used by all connections in 0N/A * that session, as well as the identities of the session's client 0N/A * Unlike {@link SSLSocket#getSession()} 0N/A * this method does not block until handshaking is complete. 0N/A * Until the initial handshake has completed, this method returns 0N/A * a session object which reports an invalid cipher suite of 0N/A * "SSL_NULL_WITH_NULL_NULL". 0N/A * @return the <code>SSLSession</code> for this <code>SSLEngine</code> 3002N/A * Returns the {@code SSLSession} being constructed during a SSL/TLS 3002N/A * TLS protocols may negotiate parameters that are needed when using 3002N/A * an instance of this class, but before the {@code SSLSession} has 3002N/A * been completely initialized and made available via {@code getSession}. 3002N/A * For example, the list of valid signature algorithms may restrict 3002N/A * the type of certificates that can used during TrustManager 3002N/A * decisions, or the maximum TLS fragment packet sizes can be 3002N/A * resized to better support the network environment. 3002N/A * This method provides early access to the {@code SSLSession} being 3002N/A * constructed. Depending on how far the handshake has progressed, 3002N/A * some data may not yet be available for use. For example, if a 3002N/A * remote server will be sending a Certificate chain, but that chain 3002N/A * has yet not been processed, the {@code getPeerCertificates} 3002N/A * method of {@code SSLSession} will throw a 3002N/A * SSLPeerUnverifiedException. Once that chain has been processed, 3002N/A * {@code getPeerCertificates} will return the proper value. 3002N/A * @see X509ExtendedKeyManager 3002N/A * @see X509ExtendedTrustManager 3002N/A * @return null if this instance is not currently handshaking, or 3002N/A * if the current handshake has not progressed far enough to 3002N/A * create a basic SSLSession. Otherwise, this method returns the 3002N/A * {@code SSLSession} currently being negotiated. 3002N/A * @throws UnsupportedOperationException if the underlying provider 3002N/A * does not implement the operation. 0N/A * Initiates handshaking (initial or renegotiation) on this SSLEngine. 0N/A * This method is not needed for the initial handshake, as the 0N/A * <code>wrap()</code> and <code>unwrap()</code> methods will 0N/A * implicitly call this method if handshaking has not already begun. 0N/A * Note that the peer may also request a session renegotiation with 0N/A * this <code>SSLEngine</code> by sending the appropriate 0N/A * session renegotiate handshake message. 0N/A * Unlike the {@link SSLSocket#startHandshake() 0N/A * SSLSocket#startHandshake()} method, this method does not block 0N/A * until handshaking is completed. 0N/A * To force a complete SSL/TLS session renegotiation, the current 0N/A * session should be invalidated prior to calling this method. 0N/A * Some protocols may not support multiple handshakes on an existing 0N/A * engine and may throw an <code>SSLException</code>. 0N/A * @throws SSLException 0N/A * if a problem was encountered while signaling the 0N/A * <code>SSLEngine</code> to begin a new handshake. 0N/A * See the class description for more information on 0N/A * has not yet been set. 0N/A * @see SSLSession#invalidate() 0N/A * Returns the current handshake status for this <code>SSLEngine</code>. 0N/A * @return the current <code>SSLEngineResult.HandshakeStatus</code>. 0N/A * Configures the engine to use client (or server) mode when 0N/A * This method must be called before any handshaking occurs. 0N/A * Once handshaking has begun, the mode can not be reset for the 0N/A * life of this engine. 0N/A * Servers normally authenticate themselves, and clients 0N/A * are not required to do so. 0N/A * @param mode true if the engine should start its handshaking 0N/A * @throws IllegalArgumentException if a mode change is attempted 0N/A * after the initial handshake has begun. 0N/A * @see #getUseClientMode() 0N/A * Returns true if the engine is set to use client mode when 0N/A * @return true if the engine should do handshaking 0N/A * @see #setUseClientMode(boolean) 0N/A * Configures the engine to <i>require</i> client authentication. This 0N/A * option is only useful for engines in the server mode. 0N/A * An engine's client authentication setting is one of the following: 0N/A * <li> client authentication required 0N/A * <li> client authentication requested 0N/A * <li> no client authentication desired 0N/A * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and 0N/A * the client chooses not to provide authentication information 0N/A * about itself, <i>the negotiations will stop and the engine will 0N/A * begin its closure procedure</i>. 0N/A * Calling this method overrides any previous setting made by 0N/A * this method or {@link #setWantClientAuth(boolean)}. 0N/A * @param need set to true if client authentication is required, 0N/A * or false if no client authentication is desired. 0N/A * @see #getNeedClientAuth() 0N/A * @see #setWantClientAuth(boolean) 0N/A * @see #getWantClientAuth() 0N/A * @see #setUseClientMode(boolean) 0N/A * Returns true if the engine will <i>require</i> client authentication. 0N/A * This option is only useful to engines in the server mode. 0N/A * @return true if client authentication is required, 0N/A * or false if no client authentication is desired. 0N/A * @see #setNeedClientAuth(boolean) 0N/A * @see #setWantClientAuth(boolean) 0N/A * @see #getWantClientAuth() 0N/A * @see #setUseClientMode(boolean) 0N/A * Configures the engine to <i>request</i> client authentication. 0N/A * This option is only useful for engines in the server mode. 0N/A * An engine's client authentication setting is one of the following: 0N/A * <li> client authentication required 0N/A * <li> client authentication requested 0N/A * <li> no client authentication desired 0N/A * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and 0N/A * the client chooses not to provide authentication information 0N/A * about itself, <i>the negotiations will continue</i>. 0N/A * Calling this method overrides any previous setting made by 0N/A * this method or {@link #setNeedClientAuth(boolean)}. 0N/A * @param want set to true if client authentication is requested, 0N/A * or false if no client authentication is desired. 0N/A * @see #getWantClientAuth() 0N/A * @see #setNeedClientAuth(boolean) 0N/A * @see #getNeedClientAuth() 0N/A * @see #setUseClientMode(boolean) 0N/A * Returns true if the engine will <i>request</i> client authentication. 0N/A * This option is only useful for engines in the server mode. 0N/A * @return true if client authentication is requested, 0N/A * or false if no client authentication is desired. 0N/A * @see #setNeedClientAuth(boolean) 0N/A * @see #getNeedClientAuth() 0N/A * @see #setWantClientAuth(boolean) 0N/A * @see #setUseClientMode(boolean) 0N/A * Controls whether new SSL sessions may be established by this engine. 0N/A * If session creations are not allowed, and there are no 0N/A * existing sessions to resume, there will be no successful 0N/A * @param flag true indicates that sessions may be created; this 0N/A * is the default. false indicates that an existing session 0N/A * @see #getEnableSessionCreation() 0N/A * Returns true if new SSL sessions may be established by this engine. 0N/A * @return true indicates that sessions may be created; this 0N/A * is the default. false indicates that an existing session 0N/A * @see #setEnableSessionCreation(boolean) 0N/A * Returns the SSLParameters in effect for this SSLEngine. 0N/A * The ciphersuites and protocols of the returned SSLParameters 0N/A * are always non-null. 0N/A * @return the SSLParameters in effect for this SSLEngine. 0N/A * Applies SSLParameters to this engine. 0N/A * <li>if <code>params.getCipherSuites()</code> is non-null, 0N/A * <code>setEnabledCipherSuites()</code> is called with that value 0N/A * <li>if <code>params.getProtocols()</code> is non-null, 0N/A * <code>setEnabledProtocols()</code> is called with that value 0N/A * <li>if <code>params.getNeedClientAuth()</code> or 0N/A * <code>params.getWantClientAuth()</code> return <code>true</code>, 0N/A * <code>setNeedClientAuth(true)</code> and 0N/A * <code>setWantClientAuth(true)</code> are called, respectively; 0N/A * otherwise <code>setWantClientAuth(false)</code> is called. 0N/A * @param params the parameters 0N/A * @throws IllegalArgumentException if the setEnabledCipherSuites() or 0N/A * the setEnabledProtocols() call fails