/* * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.net.ssl; import java.nio.ByteBuffer;import java.nio.ReadOnlyBufferException; /** * A class which enables secure communications using protocols such as * the Secure Sockets Layer (SSL) or * <A HREF="http://www.ietf.org/rfc/rfc2246.txt"> IETF RFC 2246 "Transport * Layer Security" (TLS) </A> protocols, but is transport independent. * <P> * The secure communications modes include: <UL> * * <LI> <em>Integrity Protection</em>. SSL/TLS protects against * modification of messages by an active wiretapper. * * <LI> <em>Authentication</em>. In most modes, SSL/TLS provides * peer authentication. Servers are usually authenticated, and * clients may be authenticated as requested by servers. * * <LI> <em>Confidentiality (Privacy Protection)</em>. In most * modes, SSL/TLS encrypts data being sent between client and * server. This protects the confidentiality of data, so that * passive wiretappers won't see sensitive data such as financial * information or personal information of many kinds. * * </UL> * * These kinds of protection are specified by a "cipher suite", which * is a combination of cryptographic algorithms used by a given SSL * connection. During the negotiation process, the two endpoints must * agree on a cipher suite that is available in both environments. If * there is no such suite in common, no SSL connection can be * established, and no data can be exchanged. * <P> * The cipher suite used is established by a negotiation process called * "handshaking". The goal of this process is to create or rejoin a * "session", which may protect many connections over time. After * handshaking has completed, you can access session attributes by * using the {@link #getSession()} method. * <P> * The <code>SSLSocket</code> class provides much of the same security * functionality, but all of the inbound and outbound data is * automatically transported using the underlying {@link * java.net.Socket Socket}, which by design uses a blocking model. * While this is appropriate for many applications, this model does not * provide the scalability required by large servers. * <P> * The primary distinction of an <code>SSLEngine</code> is that it * operates on inbound and outbound byte streams, independent of the * transport mechanism. It is the responsibility of the * <code>SSLEngine</code> user to arrange for reliable I/O transport to * the peer. By separating the SSL/TLS abstraction from the I/O * transport mechanism, the <code>SSLEngine</code> can be used for a * wide variety of I/O types, such as {@link * java.nio.channels.spi.AbstractSelectableChannel#configureBlocking(boolean) * non-blocking I/O (polling)}, {@link java.nio.channels.Selector * selectable non-blocking I/O}, {@link java.net.Socket Socket} and the * traditional Input/OutputStreams, local {@link java.nio.ByteBuffer * ByteBuffers} or byte arrays, <A * HREF="http://www.jcp.org/en/jsr/detail?id=203"> future asynchronous * I/O models </A>, and so on. * <P> * At a high level, the <code>SSLEngine</code> appears thus: * * <pre> * app data * * | ^ * | | | * v | | * +----+-----|-----+----+ * | | | * | SSL|Engine | * wrap() | | | unwrap() * | OUTBOUND | INBOUND | * | | | * +----+-----|-----+----+ * | | ^ * | | | * v | * * net data * </pre> * Application data (also known as plaintext or cleartext) is data which * is produced or consumed by an application. Its counterpart is * network data, which consists of either handshaking and/or ciphertext * (encrypted) data, and destined to be transported via an I/O * mechanism. Inbound data is data which has been received from the * peer, and outbound data is destined for the peer. * <P> * (In the context of an <code>SSLEngine</code>, the term "handshake * data" is taken to mean any data exchanged to establish and control a * secure connection. Handshake data includes the SSL/TLS messages * "alert", "change_cipher_spec," and "handshake.") * <P> * There are five distinct phases to an <code>SSLEngine</code>. * * <OL> * <li> Creation - The <code>SSLEngine</code> has been created and * initialized, but has not yet been used. During this phase, an * application may set any <code>SSLEngine</code>-specific settings * (enabled cipher suites, whether the <code>SSLEngine</code> should * handshake in client or server mode, and so on). Once * handshaking has begun, though, any new settings (except * client/server mode, see below) will be used for * the next handshake. * * <li> Initial Handshake - The initial handshake is a procedure by * which the two peers exchange communication parameters until an * SSLSession is established. Application data can not be sent during * this phase. * * <li> Application Data - Once the communication parameters have * been established and the handshake is complete, application data * may flow through the <code>SSLEngine</code>. Outbound * application messages are encrypted and integrity protected, * and inbound messages reverse the process. * * <li> Rehandshaking - Either side may request a renegotiation of * the session at any time during the Application Data phase. New * handshaking data can be intermixed among the application data. * Before starting the rehandshake phase, the application may * reset the SSL/TLS communication parameters such as the list of * enabled ciphersuites and whether to use client authentication, * but can not change between client/server modes. As before, once * handshaking has begun, any new <code>SSLEngine</code> * configuration settings will not be used until the next * handshake. * * <li> Closure - When the connection is no longer needed, the * application should close the <code>SSLEngine</code> and should * send/receive any remaining messages to the peer before * closing the underlying transport mechanism. Once an engine is * closed, it is not reusable: a new <code>SSLEngine</code> must * be created. * </OL> * An <code>SSLEngine</code> is created by calling {@link * SSLContext#createSSLEngine()} from an initialized * <code>SSLContext</code>. Any configuration * parameters should be set before making the first call to * <code>wrap()</code>, <code>unwrap()</code>, or * <code>beginHandshake()</code>. These methods all trigger the * initial handshake. * <P> * Data moves through the engine by calling {@link #wrap(ByteBuffer, * ByteBuffer) wrap()} or {@link #unwrap(ByteBuffer, ByteBuffer) * unwrap()} on outbound or inbound data, respectively. Depending on * the state of the <code>SSLEngine</code>, a <code>wrap()</code> call * may consume application data from the source buffer and may produce * network data in the destination buffer. The outbound data * may contain application and/or handshake data. A call to * <code>unwrap()</code> will examine the source buffer and may * advance the handshake if the data is handshaking information, or * may place application data in the destination buffer if the data * is application. The state of the underlying SSL/TLS algorithm * will determine when data is consumed and produced. * <P> * Calls to <code>wrap()</code> and <code>unwrap()</code> return an * <code>SSLEngineResult</code> which indicates the status of the * operation, and (optionally) how to interact with the engine to make * progress. * <P> * The <code>SSLEngine</code> produces/consumes complete SSL/TLS * packets only, and does not store application data internally between * calls to <code>wrap()/unwrap()</code>. Thus input and output * <code>ByteBuffer</code>s must be sized appropriately to hold the * maximum record that can be produced. Calls to {@link * SSLSession#getPacketBufferSize()} and {@link * SSLSession#getApplicationBufferSize()} should be used to determine * the appropriate buffer sizes. The size of the outbound application * data buffer generally does not matter. If buffer conditions do not * allow for the proper consumption/production of data, the application * must determine (via {@link SSLEngineResult}) and correct the * problem, and then try the call again. * <P> * For example, <code>unwrap()</code> will return a {@link * SSLEngineResult.Status#BUFFER_OVERFLOW} result if the engine * determines that there is not enough destination buffer space available. * Applications should call {@link SSLSession#getApplicationBufferSize()} * and compare that value with the space available in the destination buffer, * enlarging the buffer if necessary. Similarly, if <code>unwrap()</code> * were to return a {@link SSLEngineResult.Status#BUFFER_UNDERFLOW}, the * application should call {@link SSLSession#getPacketBufferSize()} to ensure * that the source buffer has enough room to hold a record (enlarging if * necessary), and then obtain more inbound data. * * <pre> * SSLEngineResult r = engine.unwrap(src, dst); * switch (r.getStatus()) { * BUFFER_OVERFLOW: * // Could attempt to drain the dst buffer of any already obtained * // data, but we'll just increase it to the size needed. * int appSize = engine.getSession().getApplicationBufferSize(); * ByteBuffer b = ByteBuffer.allocate(appSize + dst.position()); * dst.flip(); * b.put(dst); * dst = b; * // retry the operation. * break; * BUFFER_UNDERFLOW: * int netSize = engine.getSession().getPacketBufferSize(); * // Resize buffer if needed. * if (netSize > dst.capacity()) { * ByteBuffer b = ByteBuffer.allocate(netSize); * src.flip(); * b.put(src); * src = b; * } * // Obtain more inbound network data for src, * // then retry the operation. * break; * // other cases: CLOSED, OK. * } * </pre> * * <P> * Unlike <code>SSLSocket</code>, all methods of SSLEngine are * non-blocking. <code>SSLEngine</code> implementations may * require the results of tasks that may take an extended period of * time to complete, or may even block. For example, a TrustManager * may need to connect to a remote certificate validation service, * or a KeyManager might need to prompt a user to determine which * certificate to use as part of client authentication. Additionally, * creating cryptographic signatures and verifying them can be slow, * seemingly blocking. * <P> * For any operation which may potentially block, the * <code>SSLEngine</code> will create a {@link java.lang.Runnable} * delegated task. When <code>SSLEngineResult</code> indicates that a * delegated task result is needed, the application must call {@link * #getDelegatedTask()} to obtain an outstanding delegated task and * call its {@link java.lang.Runnable#run() run()} method (possibly using * a different thread depending on the compute strategy). The * application should continue obtaining delegated tasks until no more * exist, and try the original operation again. * <P> * At the end of a communication session, applications should properly * close the SSL/TLS link. The SSL/TLS protocols have closure handshake * messages, and these messages should be communicated to the peer * before releasing the <code>SSLEngine</code> and closing the * underlying transport mechanism. A close can be initiated by one of: * an SSLException, an inbound closure handshake message, or one of the * close methods. In all cases, closure handshake messages are * generated by the engine, and <code>wrap()</code> should be repeatedly * called until the resulting <code>SSLEngineResult</code>'s status * returns "CLOSED", or {@link #isOutboundDone()} returns true. All * data obtained from the <code>wrap()</code> method should be sent to the * peer. * <P> * {@link #closeOutbound()} is used to signal the engine that the * application will not be sending any more data. * <P> * A peer will signal its intent to close by sending its own closure * handshake message. After this message has been received and * processed by the local <code>SSLEngine</code>'s <code>unwrap()</code> * call, the application can detect the close by calling * <code>unwrap()</code> and looking for a <code>SSLEngineResult</code> * with status "CLOSED", or if {@link #isInboundDone()} returns true. * If for some reason the peer closes the communication link without * sending the proper SSL/TLS closure message, the application can * detect the end-of-stream and can signal the engine via {@link * #closeInbound()} that there will no more inbound messages to * process. Some applications might choose to require orderly shutdown * messages from a peer, in which case they can check that the closure * was generated by a handshake message and not by an end-of-stream * condition. * <P> * There are two groups of cipher suites which you will need to know * about when managing cipher suites: * * <UL> * <LI> <em>Supported</em> cipher suites: all the suites which are * supported by the SSL implementation. This list is reported * using {@link #getSupportedCipherSuites()}. * * <LI> <em>Enabled</em> cipher suites, which may be fewer than * the full set of supported suites. This group is set using the * {@link #setEnabledCipherSuites(String [])} method, and * queried using the {@link #getEnabledCipherSuites()} method. * Initially, a default set of cipher suites will be enabled on a * new engine that represents the minimum suggested * configuration. * </UL> * * Implementation defaults require that only cipher suites which * authenticate servers and provide confidentiality be enabled by * default. Only if both sides explicitly agree to unauthenticated * and/or non-private (unencrypted) communications will such a * cipher suite be selected. * <P> * Each SSL/TLS connection must have one client and one server, thus * each endpoint must decide which role to assume. This choice determines * who begins the handshaking process as well as which type of messages * should be sent by each party. The method {@link * #setUseClientMode(boolean)} configures the mode. Once the initial * handshaking has started, an <code>SSLEngine</code> can not switch * between client and server modes, even when performing renegotiations. * <P> * Applications might choose to process delegated tasks in different * threads. When an <code>SSLEngine</code> * is created, the current {@link java.security.AccessControlContext} * is saved. All future delegated tasks will be processed using this * context: that is, all access control decisions will be made using the * context captured at engine creation. * <P> * <HR> * * <B>Concurrency Notes</B>: * There are two concurrency issues to be aware of: * * <OL> * <li>The <code>wrap()</code> and <code>unwrap()</code> methods * may execute concurrently of each other. * * <li> The SSL/TLS protocols employ ordered packets. * Applications must take care to ensure that generated packets * are delivered in sequence. If packets arrive * out-of-order, unexpected or fatal results may occur. * <P> * For example: * <P> * <pre> * synchronized (outboundLock) { * sslEngine.wrap(src, dst); * outboundQueue.put(dst); * } * </pre> * * As a corollary, two threads must not attempt to call the same method * (either <code>wrap()</code> or <code>unwrap()</code>) concurrently, * because there is no way to guarantee the eventual packet ordering. * </OL> * * @see SSLContext * @see SSLSocket * @see SSLServerSocket * @see SSLSession * @see java.net.Socket * * @since 1.5 * @author Brad R. Wetmore */ public abstract class SSLEngine { private String peerHost = null; private int peerPort = -1; /** * Constructor for an <code>SSLEngine</code> providing no hints * for an internal session reuse strategy. * * @see SSLContext#createSSLEngine() * @see SSLSessionContext */ protected SSLEngine() { } /** * Constructor for an <code>SSLEngine</code>. * <P> * <code>SSLEngine</code> implementations may use the * <code>peerHost</code> and <code>peerPort</code> parameters as hints * for their internal session reuse strategy. * <P> * Some cipher suites (such as Kerberos) require remote hostname * information. Implementations of this class should use this * constructor to use Kerberos. * <P> * The parameters are not authenticated by the * <code>SSLEngine</code>. * * @param peerHost the name of the peer host * @param peerPort the port number of the peer * @see SSLContext#createSSLEngine(String, int) * @see SSLSessionContext */ protected SSLEngine(String peerHost, int peerPort) { this.peerHost = peerHost; this.peerPort = peerPort; } /** * Returns the host name of the peer. * <P> * Note that the value is not authenticated, and should not be * relied upon. * * @return the host name of the peer, or null if nothing is * available. */ public String getPeerHost() { return peerHost; } /** * Returns the port number of the peer. * <P> * Note that the value is not authenticated, and should not be * relied upon. * * @return the port number of the peer, or -1 if nothing is * available. */ public int getPeerPort() { return peerPort; } /** * Attempts to encode a buffer of plaintext application data into * SSL/TLS network data. * <P> * An invocation of this method behaves in exactly the same manner * as the invocation: * <blockquote><pre> * {@link #wrap(ByteBuffer [], int, int, ByteBuffer) * engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);} * </pre</blockquote> * * @param src * a <code>ByteBuffer</code> containing outbound application data * @param dst * a <code>ByteBuffer</code> to hold outbound network data * @return an <code>SSLEngineResult</code> describing the result * of this operation. * @throws SSLException * A problem was encountered while processing the * data that caused the <code>SSLEngine</code> to abort. * See the class description for more information on * engine closure. * @throws ReadOnlyBufferException * if the <code>dst</code> buffer is read-only. * @throws IllegalArgumentException * if either <code>src</code> or <code>dst</code> * is null. * @throws IllegalStateException if the client/server mode * has not yet been set. * @see #wrap(ByteBuffer [], int, int, ByteBuffer) */ public SSLEngineResult wrap(ByteBuffer src, ByteBuffer dst) throws SSLException { return wrap(new ByteBuffer [] { src }, 0, 1, dst); } /** * Attempts to encode plaintext bytes from a sequence of data * buffers into SSL/TLS network data. * <P> * An invocation of this method behaves in exactly the same manner * as the invocation: * <blockquote><pre> * {@link #wrap(ByteBuffer [], int, int, ByteBuffer) * engine.wrap(srcs, 0, srcs.length, dst);} * </pre</blockquote> * * @param srcs * an array of <code>ByteBuffers</code> containing the * outbound application data * @param dst * a <code>ByteBuffer</code> to hold outbound network data * @return an <code>SSLEngineResult</code> describing the result * of this operation. * @throws SSLException * A problem was encountered while processing the * data that caused the <code>SSLEngine</code> to abort. * See the class description for more information on * engine closure. * @throws ReadOnlyBufferException * if the <code>dst</code> buffer is read-only. * @throws IllegalArgumentException * if either <code>srcs</code> or <code>dst</code> * is null, or if any element in <code>srcs</code> is null. * @throws IllegalStateException if the client/server modeLines 1–500 of 1252. Load more
/* * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.net.ssl; import java.nio.ByteBuffer; import java.nio.ReadOnlyBufferException; /** * A class which enables secure communications using protocols such as * the Secure Sockets Layer (SSL) or * <A HREF="http://www.ietf.org/rfc/rfc2246.txt"> IETF RFC 2246 "Transport * Layer Security" (TLS) </A> protocols, but is transport independent. * <P> * The secure communications modes include: <UL> * * <LI> <em>Integrity Protection</em>. SSL/TLS protects against * modification of messages by an active wiretapper. * * <LI> <em>Authentication</em>. In most modes, SSL/TLS provides * peer authentication. Servers are usually authenticated, and * clients may be authenticated as requested by servers. * * <LI> <em>Confidentiality (Privacy Protection)</em>. In most * modes, SSL/TLS encrypts data being sent between client and * server. This protects the confidentiality of data, so that * passive wiretappers won't see sensitive data such as financial * information or personal information of many kinds. * * </UL> * * These kinds of protection are specified by a "cipher suite", which * is a combination of cryptographic algorithms used by a given SSL * connection. During the negotiation process, the two endpoints must * agree on a cipher suite that is available in both environments. If * there is no such suite in common, no SSL connection can be * established, and no data can be exchanged. * <P> * The cipher suite used is established by a negotiation process called * "handshaking". The goal of this process is to create or rejoin a * "session", which may protect many connections over time. After * handshaking has completed, you can access session attributes by * using the {@link #getSession()} method. * <P> * The <code>SSLSocket</code> class provides much of the same security * functionality, but all of the inbound and outbound data is * automatically transported using the underlying {@link * java.net.Socket Socket}, which by design uses a blocking model. * While this is appropriate for many applications, this model does not * provide the scalability required by large servers. * <P> * The primary distinction of an <code>SSLEngine</code> is that it * operates on inbound and outbound byte streams, independent of the * transport mechanism. It is the responsibility of the * <code>SSLEngine</code> user to arrange for reliable I/O transport to * the peer. By separating the SSL/TLS abstraction from the I/O * transport mechanism, the <code>SSLEngine</code> can be used for a * wide variety of I/O types, such as {@link * java.nio.channels.spi.AbstractSelectableChannel#configureBlocking(boolean) * non-blocking I/O (polling)}, {@link java.nio.channels.Selector * selectable non-blocking I/O}, {@link java.net.Socket Socket} and the * traditional Input/OutputStreams, local {@link java.nio.ByteBuffer * ByteBuffers} or byte arrays, <A * HREF="http://www.jcp.org/en/jsr/detail?id=203"> future asynchronous * I/O models </A>, and so on. * <P> * At a high level, the <code>SSLEngine</code> appears thus: * * <pre> * app data * * | ^ * | | | * v | | * +----+-----|-----+----+ * | | | * | SSL|Engine | * wrap() | | | unwrap() * | OUTBOUND | INBOUND | * | | | * +----+-----|-----+----+ * | | ^ * | | | * v | * * net data * </pre> * Application data (also known as plaintext or cleartext) is data which * is produced or consumed by an application. Its counterpart is * network data, which consists of either handshaking and/or ciphertext * (encrypted) data, and destined to be transported via an I/O * mechanism. Inbound data is data which has been received from the * peer, and outbound data is destined for the peer. * <P> * (In the context of an <code>SSLEngine</code>, the term "handshake * data" is taken to mean any data exchanged to establish and control a * secure connection. Handshake data includes the SSL/TLS messages * "alert", "change_cipher_spec," and "handshake.") * <P> * There are five distinct phases to an <code>SSLEngine</code>. * * <OL> * <li> Creation - The <code>SSLEngine</code> has been created and * initialized, but has not yet been used. During this phase, an * application may set any <code>SSLEngine</code>-specific settings * (enabled cipher suites, whether the <code>SSLEngine</code> should * handshake in client or server mode, and so on). Once * handshaking has begun, though, any new settings (except * client/server mode, see below) will be used for * the next handshake. * * <li> Initial Handshake - The initial handshake is a procedure by * which the two peers exchange communication parameters until an * SSLSession is established. Application data can not be sent during * this phase. * * <li> Application Data - Once the communication parameters have * been established and the handshake is complete, application data * may flow through the <code>SSLEngine</code>. Outbound * application messages are encrypted and integrity protected, * and inbound messages reverse the process. * * <li> Rehandshaking - Either side may request a renegotiation of * the session at any time during the Application Data phase. New * handshaking data can be intermixed among the application data. * Before starting the rehandshake phase, the application may * reset the SSL/TLS communication parameters such as the list of * enabled ciphersuites and whether to use client authentication, * but can not change between client/server modes. As before, once * handshaking has begun, any new <code>SSLEngine</code> * configuration settings will not be used until the next * handshake. * * <li> Closure - When the connection is no longer needed, the * application should close the <code>SSLEngine</code> and should * send/receive any remaining messages to the peer before * closing the underlying transport mechanism. Once an engine is * closed, it is not reusable: a new <code>SSLEngine</code> must * be created. * </OL> * An <code>SSLEngine</code> is created by calling {@link * SSLContext#createSSLEngine()} from an initialized * <code>SSLContext</code>. Any configuration * parameters should be set before making the first call to * <code>wrap()</code>, <code>unwrap()</code>, or * <code>beginHandshake()</code>. These methods all trigger the * initial handshake. * <P> * Data moves through the engine by calling {@link #wrap(ByteBuffer, * ByteBuffer) wrap()} or {@link #unwrap(ByteBuffer, ByteBuffer) * unwrap()} on outbound or inbound data, respectively. Depending on * the state of the <code>SSLEngine</code>, a <code>wrap()</code> call * may consume application data from the source buffer and may produce * network data in the destination buffer. The outbound data * may contain application and/or handshake data. A call to * <code>unwrap()</code> will examine the source buffer and may * advance the handshake if the data is handshaking information, or * may place application data in the destination buffer if the data * is application. The state of the underlying SSL/TLS algorithm * will determine when data is consumed and produced. * <P> * Calls to <code>wrap()</code> and <code>unwrap()</code> return an * <code>SSLEngineResult</code> which indicates the status of the * operation, and (optionally) how to interact with the engine to make * progress. * <P> * The <code>SSLEngine</code> produces/consumes complete SSL/TLS * packets only, and does not store application data internally between * calls to <code>wrap()/unwrap()</code>. Thus input and output * <code>ByteBuffer</code>s must be sized appropriately to hold the * maximum record that can be produced. Calls to {@link * SSLSession#getPacketBufferSize()} and {@link * SSLSession#getApplicationBufferSize()} should be used to determine * the appropriate buffer sizes. The size of the outbound application * data buffer generally does not matter. If buffer conditions do not * allow for the proper consumption/production of data, the application * must determine (via {@link SSLEngineResult}) and correct the * problem, and then try the call again. * <P> * For example, <code>unwrap()</code> will return a {@link * SSLEngineResult.Status#BUFFER_OVERFLOW} result if the engine * determines that there is not enough destination buffer space available. * Applications should call {@link SSLSession#getApplicationBufferSize()} * and compare that value with the space available in the destination buffer, * enlarging the buffer if necessary. Similarly, if <code>unwrap()</code> * were to return a {@link SSLEngineResult.Status#BUFFER_UNDERFLOW}, the * application should call {@link SSLSession#getPacketBufferSize()} to ensure * that the source buffer has enough room to hold a record (enlarging if * necessary), and then obtain more inbound data. * * <pre> * SSLEngineResult r = engine.unwrap(src, dst); * switch (r.getStatus()) { * BUFFER_OVERFLOW: * // Could attempt to drain the dst buffer of any already obtained * // data, but we'll just increase it to the size needed. * int appSize = engine.getSession().getApplicationBufferSize(); * ByteBuffer b = ByteBuffer.allocate(appSize + dst.position()); * dst.flip(); * b.put(dst); * dst = b; * // retry the operation. * break; * BUFFER_UNDERFLOW: * int netSize = engine.getSession().getPacketBufferSize(); * // Resize buffer if needed. * if (netSize > dst.capacity()) { * ByteBuffer b = ByteBuffer.allocate(netSize); * src.flip(); * b.put(src); * src = b; * } * // Obtain more inbound network data for src, * // then retry the operation. * break; * // other cases: CLOSED, OK. * } * </pre> * * <P> * Unlike <code>SSLSocket</code>, all methods of SSLEngine are * non-blocking. <code>SSLEngine</code> implementations may * require the results of tasks that may take an extended period of * time to complete, or may even block. For example, a TrustManager * may need to connect to a remote certificate validation service, * or a KeyManager might need to prompt a user to determine which * certificate to use as part of client authentication. Additionally, * creating cryptographic signatures and verifying them can be slow, * seemingly blocking. * <P> * For any operation which may potentially block, the * <code>SSLEngine</code> will create a {@link java.lang.Runnable} * delegated task. When <code>SSLEngineResult</code> indicates that a * delegated task result is needed, the application must call {@link * #getDelegatedTask()} to obtain an outstanding delegated task and * call its {@link java.lang.Runnable#run() run()} method (possibly using * a different thread depending on the compute strategy). The * application should continue obtaining delegated tasks until no more * exist, and try the original operation again. * <P> * At the end of a communication session, applications should properly * close the SSL/TLS link. The SSL/TLS protocols have closure handshake * messages, and these messages should be communicated to the peer * before releasing the <code>SSLEngine</code> and closing the * underlying transport mechanism. A close can be initiated by one of: * an SSLException, an inbound closure handshake message, or one of the * close methods. In all cases, closure handshake messages are * generated by the engine, and <code>wrap()</code> should be repeatedly * called until the resulting <code>SSLEngineResult</code>'s status * returns "CLOSED", or {@link #isOutboundDone()} returns true. All * data obtained from the <code>wrap()</code> method should be sent to the * peer. * <P> * {@link #closeOutbound()} is used to signal the engine that the * application will not be sending any more data. * <P> * A peer will signal its intent to close by sending its own closure * handshake message. After this message has been received and * processed by the local <code>SSLEngine</code>'s <code>unwrap()</code> * call, the application can detect the close by calling * <code>unwrap()</code> and looking for a <code>SSLEngineResult</code> * with status "CLOSED", or if {@link #isInboundDone()} returns true. * If for some reason the peer closes the communication link without * sending the proper SSL/TLS closure message, the application can * detect the end-of-stream and can signal the engine via {@link * #closeInbound()} that there will no more inbound messages to * process. Some applications might choose to require orderly shutdown * messages from a peer, in which case they can check that the closure * was generated by a handshake message and not by an end-of-stream * condition. * <P> * There are two groups of cipher suites which you will need to know * about when managing cipher suites: * * <UL> * <LI> <em>Supported</em> cipher suites: all the suites which are * supported by the SSL implementation. This list is reported * using {@link #getSupportedCipherSuites()}. * * <LI> <em>Enabled</em> cipher suites, which may be fewer than * the full set of supported suites. This group is set using the * {@link #setEnabledCipherSuites(String [])} method, and * queried using the {@link #getEnabledCipherSuites()} method. * Initially, a default set of cipher suites will be enabled on a * new engine that represents the minimum suggested * configuration. * </UL> * * Implementation defaults require that only cipher suites which * authenticate servers and provide confidentiality be enabled by * default. Only if both sides explicitly agree to unauthenticated * and/or non-private (unencrypted) communications will such a * cipher suite be selected. * <P> * Each SSL/TLS connection must have one client and one server, thus * each endpoint must decide which role to assume. This choice determines * who begins the handshaking process as well as which type of messages * should be sent by each party. The method {@link * #setUseClientMode(boolean)} configures the mode. Once the initial * handshaking has started, an <code>SSLEngine</code> can not switch * between client and server modes, even when performing renegotiations. * <P> * Applications might choose to process delegated tasks in different * threads. When an <code>SSLEngine</code> * is created, the current {@link java.security.AccessControlContext} * is saved. All future delegated tasks will be processed using this * context: that is, all access control decisions will be made using the * context captured at engine creation. * <P> * <HR> * * <B>Concurrency Notes</B>: * There are two concurrency issues to be aware of: * * <OL> * <li>The <code>wrap()</code> and <code>unwrap()</code> methods * may execute concurrently of each other. * * <li> The SSL/TLS protocols employ ordered packets. * Applications must take care to ensure that generated packets * are delivered in sequence. If packets arrive * out-of-order, unexpected or fatal results may occur. * <P> * For example: * <P> * <pre> * synchronized (outboundLock) { * sslEngine.wrap(src, dst); * outboundQueue.put(dst); * } * </pre> * * As a corollary, two threads must not attempt to call the same method * (either <code>wrap()</code> or <code>unwrap()</code>) concurrently, * because there is no way to guarantee the eventual packet ordering. * </OL> * * @see SSLContext * @see SSLSocket * @see SSLServerSocket * @see SSLSession * @see java.net.Socket * * @since 1.5 * @author Brad R. Wetmore */ public abstract class SSLEngine { private String peerHost = null; private int peerPort = -1; /** * Constructor for an <code>SSLEngine</code> providing no hints * for an internal session reuse strategy. * * @see SSLContext#createSSLEngine() * @see SSLSessionContext */ protected SSLEngine() { } /** * Constructor for an <code>SSLEngine</code>. * <P> * <code>SSLEngine</code> implementations may use the * <code>peerHost</code> and <code>peerPort</code> parameters as hints * for their internal session reuse strategy. * <P> * Some cipher suites (such as Kerberos) require remote hostname * information. Implementations of this class should use this * constructor to use Kerberos. * <P> * The parameters are not authenticated by the * <code>SSLEngine</code>. * * @param peerHost the name of the peer host * @param peerPort the port number of the peer * @see SSLContext#createSSLEngine(String, int) * @see SSLSessionContext */ protected SSLEngine(String peerHost, int peerPort) { this.peerHost = peerHost; this.peerPort = peerPort; } /** * Returns the host name of the peer. * <P> * Note that the value is not authenticated, and should not be * relied upon. * * @return the host name of the peer, or null if nothing is * available. */ public String getPeerHost() { return peerHost; } /** * Returns the port number of the peer. * <P> * Note that the value is not authenticated, and should not be * relied upon. * * @return the port number of the peer, or -1 if nothing is * available. */ public int getPeerPort() { return peerPort; } /** * Attempts to encode a buffer of plaintext application data into * SSL/TLS network data. * <P> * An invocation of this method behaves in exactly the same manner * as the invocation: * <blockquote><pre> * {@link #wrap(ByteBuffer [], int, int, ByteBuffer) * engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);} * </pre</blockquote> * * @param src * a <code>ByteBuffer</code> containing outbound application data * @param dst * a <code>ByteBuffer</code> to hold outbound network data * @return an <code>SSLEngineResult</code> describing the result * of this operation. * @throws SSLException * A problem was encountered while processing the * data that caused the <code>SSLEngine</code> to abort. * See the class description for more information on * engine closure. * @throws ReadOnlyBufferException * if the <code>dst</code> buffer is read-only. * @throws IllegalArgumentException * if either <code>src</code> or <code>dst</code> * is null. * @throws IllegalStateException if the client/server mode * has not yet been set. * @see #wrap(ByteBuffer [], int, int, ByteBuffer) */ public SSLEngineResult wrap(ByteBuffer src, ByteBuffer dst) throws SSLException { return wrap(new ByteBuffer [] { src }, 0, 1, dst); } /** * Attempts to encode plaintext bytes from a sequence of data * buffers into SSL/TLS network data. * <P> * An invocation of this method behaves in exactly the same manner * as the invocation: * <blockquote><pre> * {@link #wrap(ByteBuffer [], int, int, ByteBuffer) * engine.wrap(srcs, 0, srcs.length, dst);} * </pre</blockquote> * * @param srcs * an array of <code>ByteBuffers</code> containing the * outbound application data * @param dst * a <code>ByteBuffer</code> to hold outbound network data * @return an <code>SSLEngineResult</code> describing the result * of this operation. * @throws SSLException * A problem was encountered while processing the * data that caused the <code>SSLEngine</code> to abort. * See the class description for more information on * engine closure. * @throws ReadOnlyBufferException * if the <code>dst</code> buffer is read-only. * @throws IllegalArgumentException * if either <code>srcs</code> or <code>dst</code> * is null, or if any element in <code>srcs</code> is null. * @throws IllegalStateException if the client/server mode