| Frames | No Frames |
1: /* SSLEngine.java -- advanced, generic utility for manipulating SSL messages. 2: Copyright (C) 2006 Free Software Foundation, Inc. 3: 4: This file is a part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2 of the License, or (at 9: your option) any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; if not, write to the Free Software 18: Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 19: USA 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package javax.net.ssl; 40: 41: import java.nio.ByteBuffer; 42: 43: /** 44: * A class for low-level message wrapping and unwrapping of SSL 45: * messages. 46: * 47: * @author Casey Marshall (csm@gnu.org) 48: * @since 1.5 49: */ 50: public abstract class SSLEngine 51: { 52: private final String peerHost; 53: private final int peerPort; 54: 55: /** 56: * Creates a new SSLEngine with no peer host name or port number. 57: */ 58: protected SSLEngine () 59: { 60: this (null, -1); 61: } 62: 63: /** 64: * Creates a new SSLEngine with the specified peer host name and 65: * port number. 66: * 67: * @param peerHost The peer's host name. 68: * @param peerPort The peer's port number. 69: */ 70: protected SSLEngine (String peerHost, int peerPort) 71: { 72: this.peerHost = peerHost; 73: this.peerPort = peerPort; 74: } 75: 76: 77: 78: /** 79: * Begin, or restart, the SSL handshake. 80: * 81: * @throws SSLException 82: */ 83: public abstract void beginHandshake () throws SSLException; 84: 85: /** 86: * Close the inbound state. 87: * 88: * @throws SSLException 89: */ 90: public abstract void closeInbound () throws SSLException; 91: 92: /** 93: * Close the outbound state. 94: */ 95: public abstract void closeOutbound (); 96: 97: /** 98: * 99: */ 100: public abstract Runnable getDelegatedTask (); 101: 102: /** 103: * Returns the peer host name this SSL session is connected to, or 104: * <code>null</code> if this value was not set. 105: * 106: * @return The peer host's name. 107: */ 108: public String getPeerHost () 109: { 110: return peerHost; 111: } 112: 113: /** 114: * Returns the peer IP port number this SSL session in communicating 115: * on, or -1 if this value was not set. 116: * 117: * @return The peer's port number. 118: */ 119: public int getPeerPort () 120: { 121: return peerPort; 122: } 123: 124: /** 125: * Returns a list of SSL cipher suite names this SSLEngine is 126: * configured to use. 127: * 128: * @return The list of enabled cipher suite names. 129: */ 130: public abstract String[] getEnabledCipherSuites(); 131: 132: /** 133: * Returns a list of SSL protocol version names this SSLEngine is 134: * configured to use. 135: * 136: * @return The list of enabled protocol names. 137: */ 138: public abstract String[] getEnabledProtocols (); 139: 140: /** 141: * Tells if sessions will be created by this engine, and therefore 142: * may be resumed at a later time. 143: * 144: * @return True if sessions will be created. 145: */ 146: public abstract boolean getEnableSessionCreation(); 147: 148: /** 149: * Return the current handshake status. 150: * 151: * @return The current handshake status. 152: */ 153: public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus (); 154: 155: /** 156: * Tells if this SSLEngine is configured to require client 157: * authentication when in server mode. 158: * 159: * @return True iff client authentication is required. 160: */ 161: public abstract boolean getNeedClientAuth (); 162: 163: /** 164: * Return the {@link SSLSession} object this connection represents. 165: * 166: * @return The SSL session. 167: */ 168: public abstract SSLSession getSession (); 169: 170: /** 171: * Returns a list of SSL cipher suite names this SSLEngine 172: * implementation supports. 173: * 174: * @return The list of cipher suite names supported by this 175: * implementation. 176: */ 177: public abstract String[] getSupportedCipherSuites (); 178: 179: /** 180: * Returns a list of SSL protocol version names this SSLEngine 181: * implementation supports. SSL protocol names include things like 182: * "SSLv3" or "TLSv1". 183: * 184: * @return The list of SSL protocol names 185: */ 186: public abstract String[] getSupportedProtocols (); 187: 188: /** 189: * Tells if this SSLEngine is a "client" session. 190: * 191: * @return True iff this session is configured for client mode. 192: */ 193: public abstract boolean getUseClientMode (); 194: 195: /** 196: * Tells if client authentication is requested, but not required, 197: * for sessions in server mode. If true, a server session will 198: * request an authentication message from connecting clients, but 199: * will still allow clients to connect if they cannot be 200: * authenticated. 201: * 202: * @return True iff client authentication is requested. 203: */ 204: public abstract boolean getWantClientAuth (); 205: 206: /** 207: * Tells if the incoming data stream is finished, and thus if no 208: * more data will be available to be unwrapped. 209: * 210: * @return True if no more data is to be unwrapped. 211: */ 212: public abstract boolean isInboundDone (); 213: 214: /** 215: * Tells if the outgoing data stream is finished, and thus if no 216: * more data may be wrapped. 217: * 218: * @return True if no more data may be wrapped. 219: */ 220: public abstract boolean isOutboundDone (); 221: 222: /** 223: * Sets the list of enabled cipher suites. The argument is an array 224: * of strings of the canonical suite names. 225: * 226: * @param suites The cipher suites to enable. 227: * @throws IllegalArgumentException If any of the specified suite 228: * strings is not supported by this implementation, or if the 229: * argument is null. 230: */ 231: public abstract void setEnabledCipherSuites (String[] suites); 232: 233: /** 234: * Sets the list of enabled protocol versions. The argument is an 235: * array of strings of the canonical protocol version names, such as 236: * "TLSv1". 237: * 238: * @param protocols The protocol versions to enable. 239: * @throws IllegalArgumentException If any of the specified 240: * protocols are not supported, or if the argument is null. 241: */ 242: public abstract void setEnabledProtocols (String[] protocols); 243: 244: /** 245: * Enables or disables session creation. If enabled, each connection 246: * will create session that may be resumed by another connection. 247: * 248: * @param create Whether or not to enable session creation. 249: */ 250: public abstract void setEnableSessionCreation (boolean create); 251: 252: /** 253: * Enables client or server mode. If the argument is true, this 254: * engine will run in client mode; if false, server mode. 255: * 256: * @param clientMode Whether or not to use client mode. 257: */ 258: public abstract void setUseClientMode (boolean clientMode); 259: 260: /** 261: * Enables or disables required client authentication. If enabled, 262: * clients may only connect if they provide proper identification. 263: * 264: * <p>This parameter is only used in server mode. 265: * 266: * @param needAuth Whether or not client authentication is required. 267: */ 268: public abstract void setNeedClientAuth (boolean needAuth); 269: 270: /** 271: * Enables or disables requested client authentication. If enabled, 272: * clients will be asked to provide proper identification, but will 273: * still be allowed to connect if they do not provide it. 274: * 275: * <p>This parameter is only used in server mode. 276: * 277: * @param wantAuth Whether or not client authentication will be 278: * requested, but not required. 279: */ 280: public abstract void setWantClientAuth (boolean wantAuth); 281: 282: /** 283: * Unwraps a byte buffer recieved from the network, storing the 284: * decrypted, unwrapped bytes into the given buffer. 285: * 286: * <p>This call is exactly equivalent to <code>unwrap (source, new 287: * ByteBuffer[] { sink }, 0, 1)</code>. 288: * 289: * @param source The source bytes, coming from the network. 290: * @param sink The buffer to hold the unwrapped message. 291: * @return An engine result object for the operation. 292: * @throws SSLException If an SSL message parsing error occurs. 293: * @throws java.nio.ReadOnlyBufferException If 'sink' is not 294: * writable. 295: * @throws IllegalArgumentException If either 'source' or 'sink' is 296: * null. 297: * @throws IllegalStateException If this engine has not been put 298: * into client or server mode. 299: */ 300: public SSLEngineResult unwrap (ByteBuffer source, ByteBuffer sink) 301: throws SSLException 302: { 303: return unwrap (source, new ByteBuffer[] { sink }, 0, 1); 304: } 305: 306: /** 307: * Unwraps a byte buffer recieved from the network, storing the 308: * decrypted, unwrapped bytes into the given buffers. 309: * 310: * <p>This call is exactly equivalent to <code>unwrap (source, 311: * sinks, 0, sinks.length)</code>. 312: * 313: * @param source The source bytes, coming from the network. 314: * @param sinks The buffers to hold the unwrapped message. 315: * @return An engine result object for the operation. 316: * @throws SSLException If an SSL message parsing error occurs. 317: * @throws java.nio.ReadOnlyBufferException If any buffer in 'sinks' 318: * is not writable. 319: * @throws IllegalArgumentException If either 'source' or 'sinks' is 320: * null. 321: * @throws IllegalStateException If this engine has not been put 322: * into client or server mode. 323: */ 324: public SSLEngineResult unwrap (ByteBuffer source, ByteBuffer[] sinks) 325: throws SSLException 326: { 327: return unwrap (source, sinks, 0, sinks.length); 328: } 329: 330: /** 331: * Unwraps a byte buffer received from the network, storing the 332: * decrypted, unwrapped bytes into the given buffers. After 333: * unwrapping, the bytes placed into the sink buffers are ready for 334: * consumption by the application. 335: * 336: * <p>This method may place no bytes in the destination buffer; for 337: * example, if this engine is still performing the SSL handshake, 338: * only handshake data will be consumed, and no application data. 339: * 340: * <p>It is stated that this method may modify the source buffer, 341: * and that it must not be passed to another SSLEngine (SSL 342: * connections are independent, so another SSLEngine will not have 343: * the parameters or state to handle messages meant for this 344: * engine). 345: * 346: * @param source The source bytes, coming from the network. 347: * @param sinks The buffers to hold the unwrapped message. 348: * @param offset The index of the first buffer in 'sinks' to use. 349: * @param length The number of buffers in 'sinks' to use. 350: * @return An engine result object for the operation. 351: * @throws SSLException If an SSL message parsing error occurs. 352: * @throws java.nio.ReadOnlyBufferException If any buffer in 'sinks' 353: * is not writable. 354: * @throws IllegalArgumentException If either 'source' or 'sinks' is 355: * null. 356: * @throws IllegalStateException If this engine has not been put 357: * into client or server mode. 358: * @throws IndexOutOfBoundsException If 'offset' or 'length' is 359: * negative, or if 'length+offset' is greater than 'sinks.length'. 360: */ 361: public abstract SSLEngineResult unwrap (ByteBuffer source, 362: ByteBuffer[] sinks, int offset, 363: int length) 364: throws javax.net.ssl.SSLException; 365: 366: /** 367: * Wraps a byte buffer into an SSL message, for preparation to send 368: * it over the network. 369: * 370: * <p>This method is exactly equivalent to <code>wrap (new 371: * ByteBuffer[] { source }, 0, 1, sink)</code>. 372: * 373: * @param source The source buffer with application data. 374: * @param sink The buffer to hold the wrapped data. 375: * @return An engine result object for the operation. 376: * @throws SSLException If an SSL error occurs. 377: * @throws java.nio.ReadOnlyBufferException If 'sink' is read-only. 378: * @throws IllegalArgumentException If either 'source' or 'sink' is 379: * null. 380: * @throws IllegalStateException If this engine has not been put 381: * into client or server mode. 382: */ 383: public SSLEngineResult wrap (ByteBuffer source, ByteBuffer sink) 384: throws SSLException 385: { 386: return wrap (new ByteBuffer[] { source }, 0, 1, sink); 387: } 388: 389: /** 390: * Wraps byte buffers into an SSL message, for preparation to send 391: * them over the network. 392: * 393: * <p>This method is exactly equivalent to <code>wrap (sources, 0, 394: * 1, sink)</code>. 395: * 396: * @param sources The source buffers with application data. 397: * @param sink The buffer to hold the wrapped data. 398: * @return An engine result object for the operation. 399: * @throws SSLException If an SSL error occurs. 400: * @throws java.nio.ReadOnlyBufferException If 'sink' is read-only. 401: * @throws IllegalArgumentException If either 'sources' or 'sink' is 402: * null. 403: * @throws IllegalStateException If this engine has not been put 404: * into client or server mode. 405: */ 406: public SSLEngineResult wrap (ByteBuffer[] sources, ByteBuffer sink) 407: throws SSLException 408: { 409: return wrap (sources, 0, sources.length, sink); 410: } 411: 412: /** 413: * Wraps byte buffers into an SSL message, for preparation to send 414: * them over the network. After wrapping, the data in the sink 415: * buffer is ready to be sent over the transport layer. 416: * 417: * <p>This method may consume no data from the source buffers, and 418: * yet still produce output that should be sent accross the wire; 419: * for example if this engine has not yet completed the SSL 420: * handshake, the sink buffer will be filled with handshake 421: * messages. 422: * 423: * @param sources The source buffers with application data. 424: * @param offset The offset into the source buffers to start reading 425: * application data. 426: * @param length The number of buffers to read from 'sources'. 427: * @param sink The buffer to hold the wrapped data. 428: * @return An engine result object for the operation. 429: * @throws SSLException If an SSL error occurs. 430: * @throws java.nio.ReadOnlyBufferException If 'sink' is read-only. 431: * @throws IllegalArgumentException If either 'sources' or 'sink' is 432: * null. 433: * @throws IllegalStateException If this engine has not been put 434: * into client or server mode. 435: * @throws IndexOutOfBoundsException If 'offset' or 'length' is 436: * negative, or if 'length+offset' is greater than 'sources.length'. 437: */ 438: public abstract SSLEngineResult wrap (ByteBuffer[] sources, int offset, 439: int length, ByteBuffer sink) 440: throws SSLException; 441: 442: }