Source for javax.net.ssl.SSLEngine

   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: }