Source for org.ietf.jgss.GSSContext

   1: /* GSSContext.java -- The GSS context interface.
   2:    Copyright (C) 2004 Free Software Foundation, Inc.
   3: 
   4: This file is 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, or (at your option)
   9: 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; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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 org.ietf.jgss;
  40: 
  41: import java.io.InputStream;
  42: import java.io.OutputStream;
  43: 
  44: /**
  45:  * <p>This interface encapsulates the GSS-API security context and provides
  46:  * the security services ({@link #wrap(byte[],int,int,org.ietf.jgss.MessageProp)},
  47:  * {@link #unwrap(byte[],int,int,org.ietf.jgss.MessageProp)}, {@link
  48:  * #getMIC(byte[],int,int,org.ietf.jgss.MessageProp)}, {@link
  49:  * #verifyMIC(byte[],int,int,byte[],int,int,org.ietf.jgss.MessageProp)}) that
  50:  * are available over the context.  Security contexts are established
  51:  * between peers using locally acquired credentials.  Multiple contexts
  52:  * may exist simultaneously between a pair of peers, using the same or
  53:  * different set of credentials.  GSS-API functions in a manner
  54:  * independent of the underlying transport protocol and depends on its
  55:  * calling application to transport its tokens between peers.</p>
  56:  *
  57:  * <p>Before the context establishment phase is initiated, the context
  58:  * initiator may request specific characteristics desired of the
  59:  * established context.  These can be set using the set methods.  After
  60:  * the context is established, the caller can check the actual
  61:  * characteristic and services offered by the context using the query
  62:  * methods.</p>
  63:  *
  64:  * <p>The context establishment phase begins with the first call to the
  65:  * init method by the context initiator.  During this phase the
  66:  * {@link #initSecContext(byte[],int,int)} and {@link
  67:  * #acceptSecContext(byte[],int,int)} methods will produce GSS-API
  68:  * authentication tokens which the calling application needs to send to
  69:  * its peer.  If an error occurs at any point, an exception will get
  70:  * thrown and the code will start executing in a catch block.  If not,
  71:  * the normal flow of code continues and the application can make a call
  72:  * to the {@link #isEstablished()} method. If this method returns false it
  73:  * indicates that a token is needed from its peer in order to continue
  74:  * the context establishment phase.  A return value of true signals that
  75:  * the local end of the context is established.  This may still require
  76:  * that a token be sent to the peer, if one is produced by GSS-API.
  77:  * During the context establishment phase, the {@link #isProtReady()}
  78:  * method may be called to determine if the context can be used for the
  79:  * per-message operations.  This allows applications to use per-message
  80:  * operations on contexts which aren't fully established.</p>
  81:  *
  82:  * <p>After the context has been established or the {@link #isProtReady()}
  83:  * method returns <code>true</code>, the query routines can be invoked to
  84:  * determine the actual characteristics and services of the established
  85:  * context.  The application can also start using the per-message methods
  86:  * of {@link #wrap(byte[],int,int,org.ietf.jgss.MessageProp)} and
  87:  * {@link #getMIC(byte[],int,int,org.ietf.jgss.MessageProp)} to obtain
  88:  * cryptographic operations on application supplied data.</p>
  89:  *
  90:  * <p>When the context is no longer needed, the application should call
  91:  * {@link dispose()} to release any system resources the context may be
  92:  * using.</p>
  93:  *
  94:  * <h3>Example Code</h3>
  95:  *
  96:  * <pre>
  97: GSSManager mgr = GSSManager.getInstance();
  98: 
  99: // start by creating the name for a service entity
 100: GSSName targetName = mgr.createName("service@host",
 101:                                     GSSName.NT_HOSTBASED_SERVICE);
 102: 
 103: // create a context using default credentials for the above entity
 104: // and the implementation specific default mechanism
 105: GSSContext context = mgr.createContext(targetName,
 106:                                        null,   // default mechanism
 107:                                        null,   // default credentials
 108:                                        GSSContext.INDEFINITE_LIFETIME);
 109: 
 110: // set desired context options - all others are false by default
 111: context.requestConf(true);
 112: context.requestMutualAuth(true);
 113: context.requestReplayDet(true);
 114: context.requestSequenceDet(true);
 115: 
 116: // establish a context between peers - using byte arrays
 117: byte []inTok = new byte[0];
 118: 
 119: try
 120:   {
 121:     do
 122:       {
 123:         byte[] outTok = context.initSecContext(inTok, 0,
 124:                                                inTok.length);
 125: 
 126:         // send the token if present
 127:         if (outTok != null)
 128:           sendToken(outTok);
 129: 
 130:         // check if we should expect more tokens
 131:         if (context.isEstablished())
 132:           break;
 133: 
 134:         // another token expected from peer
 135:         inTok = readToken();
 136: 
 137:       }
 138:     while (true);
 139:   }
 140: catch (GSSException e)
 141:   {
 142:     print("GSSAPI error: " + e.getMessage());
 143:   }
 144: 
 145: // display context information
 146: print("Remaining lifetime in seconds = " + context.getLifetime());
 147: print("Context mechanism = " + context.getMech().toString());
 148: print("Initiator = " + context.getSrcName().toString());
 149: print("Acceptor = " + context.getTargName().toString());
 150: 
 151: if (context.getConfState())
 152:   print("Confidentiality security service available");
 153: 
 154: if (context.getIntegState())
 155:   print("Integrity security service available");
 156: 
 157: // perform wrap on an application supplied message, appMsg,
 158: // using QOP = 0, and requesting privacy service
 159: byte[] appMsg ...
 160: MessageProp mProp = new MessageProp(0, true);
 161: byte[] tok = context.wrap(appMsg, 0, appMsg.length, mProp);
 162: 
 163: if (mProp.getPrivacy())
 164:   print("Message protected with privacy.");
 165: 
 166: sendToken(tok);
 167: 
 168: 
 169: // release the local-end of the context
 170: context.dispose();
 171:  * </pre>
 172:  */
 173: public interface GSSContext
 174: {
 175: 
 176:   // Constants.
 177:   // -------------------------------------------------------------------------
 178: 
 179:   /**
 180:    * A lifetime constant representing the default context lifetime.
 181:    */
 182:   int DEFAULT_LIFETIME = 0;
 183: 
 184:   /**
 185:    * A lifetime constant representing indefinite context lifetime.
 186:    */
 187:   int INDEFINITE_LIFETIME = Integer.MAX_VALUE;
 188: 
 189:   // Methods.
 190:   // -------------------------------------------------------------------------
 191: 
 192:   /**
 193:    * <p>Called by the context initiator to start the context creation
 194:    * process.  This is equivalent to the stream based method except that
 195:    * the token buffers are handled as byte arrays instead of using stream
 196:    * objects.  This method may return an output token which the
 197:    * application will need to send to the peer for processing by the
 198:    * accept call.  Typically, the application would do so by calling the
 199:    * {@link OutputStream#flush()} method on an OutputStream that
 200:    * encapsulates the connection between the two peers.  The application
 201:    * can call {@link #isEstablished()} to determine if the context
 202:    * establishment phase is complete for this peer.  A return value of
 203:    * <code>false</code> from {@link #isEstablished()} indicates that more
 204:    * tokens are expected to be supplied to the initSecContext() method. Note
 205:    * that it is possible that the initSecContext() method return a token for
 206:    * the peer, and {@link #isEstablished()} to return <code>true</code> also.
 207:    * This indicates that the token needs to be sent to the peer, but the local
 208:    * end of the context is now fully established.</p>
 209:    *
 210:    * <p>Upon completion of the context establishment, the available context
 211:    * options may be queried through the get methods.</p>
 212:    *
 213:    * @param inputBuf Token generated by the peer. This parameter is ignored
 214:    *                 on the first call.
 215:    * @param offset   The offset within the <i>inputBuf</i> where the token
 216:    *                 begins.
 217:    * @param len      The length of the token within the <i>inputBuf</i>
 218:    *                 (starting at the offset).
 219:    * @return The output token, if any.
 220:    * @throws GSSException If this operation fails.
 221:    */
 222:   byte[] initSecContext(byte[] inputBuf, int offset, int len)
 223:     throws GSSException;
 224: 
 225:   /**
 226:    * <p>Called by the context initiator to start the context creation
 227:    * process.  This is equivalent to the byte array based method.  This
 228:    * method may write an output token to the <i>outStream</i>, which the
 229:    * application will need to send to the peer for processing by the
 230:    * accept call. Typically, the application would do so by calling the
 231:    * {@link OutputStream#flush()} method on an OutputStream that encapsulates
 232:    * the connection between the two peers. The application can call {@link
 233:    * #isEstablished()} to determine if the context establishment phase is
 234:    * complete for this peer. A return value of <code>false</code> from
 235:    * isEstablished indicates that more tokens are expected to be supplied
 236:    * to the initSecContext() method. Note that it is possible that the
 237:    * initSecContext() method return a token for the peer, and {@link
 238:    * #isEstablished() return <code>true</code> also. This indicates that
 239:    * the token needs to be sent to the peer, but the local end of the context
 240:    * is now fully established.</p>
 241:    *
 242:    * <p>The GSS-API authentication tokens contain a definitive start and end.
 243:    * This method will attempt to read one of these tokens per invocation,
 244:    * and may block on the stream if only part of the token is available.</p>
 245:    *
 246:    * <p>Upon completion of the context establishment, the available context
 247:    * options may be queried through the get methods.</p>
 248:    *
 249:    * @param inStream  Contains the token generated by the peer. This
 250:    *                  parameter is ignored on the first call.
 251:    * @param outStream Output stream where the output token will be written.
 252:    *                  During the final stage of context establishment, there
 253:    *                  may be no bytes written.
 254:    * @return The number of bytes written to <i>outStream</i>, or 0 if no
 255:    *         token is written.
 256:    * @throws GSSException If this operation fails.
 257:    */
 258:   int initSecContext(InputStream inStream, OutputStream outStream)
 259:     throws GSSException;
 260: 
 261:   /**
 262:    * <p>Called by the context acceptor upon receiving a token from the peer.
 263:    * This call is equivalent to the stream based method except that the
 264:    * token buffers are handled as byte arrays instead of using stream
 265:    * objects.</p>
 266:    *
 267:    * <p>This method may return an output token which the application will
 268:    * need to send to the peer for further processing by the init call.</p>
 269:    *
 270:    * <p><code>null</code> return value indicates that no token needs to be
 271:    * sent to the peer. The application can call {@link #isEstablished()}
 272:    * to determine if the context establishment phase is complete for this
 273:    * peer. A return value of <code>false</code> from {@link #isEstablished()}
 274:    * indicates that more tokens are expected to be supplied to this
 275:    * method.</p>
 276:    *
 277:    * <p>Note that it is possible that acceptSecContext() return a token for
 278:    * the peer, and isEstablished() return <code>true</code> also. This
 279:    * indicates that the token needs to be sent to the peer, but the local
 280:    * end of the context is now fully established.</p>
 281:    *
 282:    * <p>Upon completion of the context establishment, the available context
 283:    * options may be queried through the get methods.</p>
 284:    *
 285:    * @param inTok  Token generated by the peer.
 286:    * @param offset The offset within the <i>inTok</i> where the token begins.
 287:    * @param len    The length of the token within the <i>inTok</i> (starting
 288:    *               at the offset).
 289:    * @return The output token, if any.
 290:    * @throws GSSException If this operation fails.
 291:    */
 292:   byte[] acceptSecContext(byte[] inTok, int offset, int len)
 293:     throws GSSException;
 294: 
 295:   /**
 296:    * <p>Called by the context acceptor upon receiving a token from the peer.
 297:    * This call is equivalent to the byte array method.  It may write an
 298:    * output token to the outStream, which the application will need to
 299:    * send to the peer for processing by its initSecContext method.
 300:    * Typically, the application would do so by calling the {@link
 301:    * OutputStream#flush()} method on an OutputStream that encapsulates the
 302:    * connection between the two peers. The application can call {@link
 303:    * #isEstablished()} to determine if the context establishment phase is
 304:    * complete for this peer. A return value of <code>false</code> from
 305:    * {@link #isEstablished()} indicates that more tokens are expected to be
 306:    * supplied to this method.</p>
 307:    *
 308:    * <p>Note that it is possible that acceptSecContext() return a token for
 309:    * the peer, and isEstablished() return <code>true</code> also. This
 310:    * indicates that the token needs to be sent to the peer, but the local
 311:    * end of the context is now fully established.</p>
 312:    *
 313:    * <p>The GSS-API authentication tokens contain a definitive start and end.
 314:    * This method will attempt to read one of these tokens per invocation,
 315:    * and may block on the stream if only part of the token is available.</p>
 316:    *
 317:    * <p>Upon completion of the context establishment, the available context
 318:    * options may be queried through the get methods.</p>
 319:    *
 320:    * @param inStream  Contains the token generated by the peer.
 321:    * @param outStream Output stream where the output token will be written.
 322:    *                  During the final stage of context establishment, there
 323:    *                  may be no bytes written.
 324:    * @return The number of bytes written, or 0 if no token is written.
 325:    * @throws GSSException If this operation fails.
 326:    */
 327:   void acceptSecContext(InputStream inStream, OutputStream outStream)
 328:     throws GSSException;
 329: 
 330:   /**
 331:    * Used during context establishment to determine the state of the
 332:    * context. Returns <code>true</code> if this is a fully established
 333:    * context on the caller's side and no more tokens are needed from the
 334:    * peer. Should be called after a call to {@link
 335:    * #initSecContext(byte[],int,int)} or {@link
 336:    * #acceptSecContext(byte[],int,int)} when no {@link GSSException}
 337:    * is thrown.
 338:    *
 339:    * @return True of this context is fully established on this side.
 340:    */
 341:   boolean isEstablished();
 342: 
 343:   /**
 344:    * Releases any system resources and cryptographic information stored in
 345:    * the context object. This will invalidate the context.
 346:    *
 347:    * @throws GSSException If this operation fails.
 348:    */
 349:   void dispose() throws GSSException;
 350: 
 351:   /**
 352:    * <p>Returns the maximum message size that, if presented to the
 353:    * {@link #wrap(byte[],int,int,org.ietf.jgss.MessageProp)} method with
 354:    * the same <i>confReq</i> and <i>qop</i> parameters, will result in an
 355:    * output token containing no more than the <i>maxTokenSize</i> bytes.</p>
 356:    *
 357:    * <p>This call is intended for use by applications that communicate over
 358:    * protocols that impose a maximum message size.  It enables the
 359:    * application to fragment messages prior to applying protection.</p>
 360:    *
 361:    * <p>GSS-API implementations are recommended but not required to detect
 362:    * invalid QOP values when getWrapSizeLimit is called.  This routine
 363:    * guarantees only a maximum message size, not the availability of
 364:    * specific QOP values for message protection.</p>
 365:    *
 366:    * <p>Successful completion of this call does not guarantee that wrap will
 367:    * be able to protect a message of the computed length, since this
 368:    * ability may depend on the availability of system resources at the
 369:    * time that wrap is called.  However, if the implementation itself
 370:    * imposes an upper limit on the length of messages that may be
 371:    * processed by wrap, the implementation should not return a value that
 372:    * is greater than this length.</p>
 373:    *
 374:    * @param qop          Indicates the level of protection wrap will be asked
 375:    *                     to provide.
 376:    * @param confReq      Indicates if wrap will be asked to provide privacy
 377:    *                     service.
 378:    * @param maxTokenSize The desired maximum size of the token emitted
 379:    *                     by {@link #wrap(byte[],int,int,org.ietf.jgss.MessageProp)}.
 380:    * @return The maximum wrapped output size.
 381:    * @throws GSSException If this operation fails.
 382:    */
 383:   int getWrapSizeLimit(int qop, boolean confReq, int maxTokenSize)
 384:     throws GSSException;
 385: 
 386:   /**
 387:    * <p>Applies per-message security services over the established security
 388:    * context.  The method will return a token with a cryptographic MIC and
 389:    * may optionally encrypt the specified <i>inBuf</i>. This method is
 390:    * equivalent in functionality to its stream counterpart. The returned
 391:    * byte array will contain both the MIC and the message.</p>
 392:    *
 393:    * <p>The {@link MessageProp} object is instantiated by the application
 394:    * and used to specify a QOP value which selects cryptographic algorithms,
 395:    * and a privacy service to optionally encrypt the message. The underlying
 396:    * mechanism that is used in the call may not be able to provide the
 397:    * privacy service.  It sets the actual privacy service that it does
 398:    * provide in this {@link MessageProp} object which the caller should then
 399:    * query upon return. If the mechanism is not able to provide the
 400:    * requested QOP, it throws a {@link GSSException} with the {@link
 401:    * GSSException#BAD_QOP} code.</p>
 402:    *
 403:    * <p>Since some application-level protocols may wish to use tokens emitted
 404:    * by wrap to provide "secure framing", implementations should support
 405:    * the wrapping of zero-length messages.</p>
 406:    *
 407:    * <p>The application will be responsible for sending the token to the
 408:    * peer.</p>
 409:    *
 410:    * @param inBuf   Application data to be protected.
 411:    * @param offset  The offset within the inBuf where the data begins.
 412:    * @param len     The length of the data within the inBuf (starting at
 413:    *                the offset).
 414:    * @param msgProp Instance of {@link MessageProp} that is used by the
 415:    *                application to set the desired QOP and privacy state.
 416:    *                Set the desired QOP to 0 to request the default QOP.
 417:    *                Upon return from this method, this object will contain
 418:    *                the the actual privacy state that was applied to the
 419:    *                message by the underlying mechanism.
 420:    * @return The wrapped data.
 421:    * @throws GSSException If this operation fails.
 422:    */
 423:   byte[] wrap(byte[] inBuf, int offset, int len, MessageProp msgProp)
 424:     throws GSSException;
 425: 
 426:   /**
 427:    * <p>Allows to apply per-message security services over the established
 428:    * security context.  The method will produce a token with a
 429:    * cryptographic MIC and may optionally encrypt the message in inStream.
 430:    * The outStream will contain both the MIC and the message.</p>
 431:    *
 432:    * <p>The {@link MessageProp} object is instantiated by the application and
 433:    * used to specify a QOP value which selects cryptographic algorithms, and
 434:    * a privacy service to optionally encrypt the message.  The underlying
 435:    * mechanism that is used in the call may not be able to provide the
 436:    * privacy service.  It sets the actual privacy service that it does
 437:    * provide in this MessageProp object which the caller should then query
 438:    * upon return.  If the mechanism is not able to provide the requested
 439:    * QOP, it throws a {@link GSSException} with the {@link
 440:    * GSSException#BAD_QOP} code.</p>
 441:    *
 442:    * <p>Since some application-level protocols may wish to use tokens emitted
 443:    * by wrap to provide "secure framing", implementations should support
 444:    * the wrapping of zero-length messages.</p>
 445:    *
 446:    * <p>The application will be responsible for sending the token to the
 447:    * peer.</p>
 448:    *
 449:    * @param inStream  Input stream containing the application data to be
 450:    *                  protected.
 451:    * @param outStream The output stream to write the protected message to.
 452:    *                  The application is responsible for sending this to the
 453:    *                  other peer for processing in its unwrap method.
 454:    * @param msgProp   Instance of {@link MessageProp} that is used by the
 455:    *                  application to set the desired QOP and privacy state.
 456:    *                  Set the desired QOP to 0 to request the default QOP.
 457:    *                  Upon return from this method, this object will contain
 458:    *                  the the actual privacy state that was applied to the
 459:    *                  message by the underlying mechanism.
 460:    * @throws GSSException If this operation fails.
 461:    */
 462:   void wrap(InputStream inStream, OutputStream outStream, MessageProp msgProp)
 463:     throws GSSException;
 464: 
 465:   /**
 466:    * <p>Used by the peer application to process tokens generated with the
 467:    * wrap call. This call is equal in functionality to its stream
 468:    * counterpart. The method will return the message supplied in the peer
 469:    * application to the wrap call, verifying the embedded MIC.</p>
 470:    *
 471:    * <p>The {@link MessageProp} object is instantiated by the application and
 472:    * is used by the underlying mechanism to return information to the caller
 473:    * such as the QOP, whether confidentiality was applied to the message, and
 474:    * other supplementary message state information.</p>
 475:    *
 476:    * <p>Since some application-level protocols may wish to use tokens emitted
 477:    * by wrap to provide "secure framing", implementations should support
 478:    * the wrapping and unwrapping of zero-length messages.</p>
 479:    *
 480:    * @param inBuf   GSS-API wrap token received from peer.
 481:    * @param offset  The offset within the inBuf where the token begins.
 482:    * @param len     The length of the token within the inBuf (starting at
 483:    *                the offset).
 484:    * @param msgProp Upon return from the method, this object will contain
 485:    *                the applied QOP, the privacy state of the message, and
 486:    *                supplementary information stating whether the token was
 487:    *                a duplicate, old, out of sequence or arriving after a gap.
 488:    * @return The unwrapped token.
 489:    * @throws GSSException If this operation fails.
 490:    */
 491:   byte[] unwrap(byte[] inBuf, int offset, int len, MessageProp msgProp)
 492:     throws GSSException;
 493: 
 494:   /**
 495:    * <p>Used by the peer application to process tokens generated with the
 496:    * wrap call.  This call is equal in functionality to its byte array
 497:    * counterpart.  It will produce the message supplied in the peer
 498:    * application to the wrap call, verifying the embedded MIC.</p>
 499:    *
 500:    * <p>The {@link MessageProp} object is instantiated by the application
 501:    * and is used by the underlying mechanism to return information to the
 502:    * caller such as the QOP, whether confidentiality was applied to the
 503:    * message, and other supplementary message state information.</p>
 504:    *
 505:    * <p>Since some application-level protocols may wish to use tokens emitted
 506:    * by wrap to provide "secure framing", implementations should support
 507:    * the wrapping and unwrapping of zero-length messages.</p>
 508:    *
 509:    * @param inStream  Input stream containing the GSS-API wrap token
 510:    *                  received from the peer.
 511:    * @param outStream The output stream to write the application message to.
 512:    * @param msgProp   Upon return from the method, this object will contain
 513:    *                  the applied QOP, the privacy state of the message, and
 514:    *                  supplementary information stating whether the token was
 515:    *                  a duplicate, old, out of sequence or arriving after a gap.
 516:    * @throws GSSException If this operation fails.
 517:    */
 518:   void unwrap(InputStream inStream, OutputStream outStream, MessageProp msgProp)
 519:     throws GSSException;
 520: 
 521:   /**
 522:    * <p>Returns a token containing a cryptographic MIC for the supplied
 523:    * message, for transfer to the peer application.  Unlike wrap, which
 524:    * encapsulates the user message in the returned token, only the message
 525:    * MIC is returned in the output token.  This method is identical in
 526:    * functionality to its stream counterpart.</p>
 527:    *
 528:    * <p>Note that privacy can only be applied through the wrap call.</p>
 529:    *
 530:    * <p>Since some application-level protocols may wish to use tokens emitted
 531:    * by getMIC to provide "secure framing", implementations should support
 532:    * derivation of MICs from zero-length messages.</p>
 533:    *
 534:    * @param inMsg   Message to generate MIC over.
 535:    * @param offset  The offset within the inMsg where the token begins.
 536:    * @param len     The length of the token within the inMsg (starting at
 537:    *                the offset).
 538:    * @param msgProp Instance of MessageProp that is used by the
 539:    *                application to set the desired QOP.  Set the desired
 540:    *                QOP to 0 in msgProp to request the default QOP.
 541:    *                Alternatively pass in <code>null</code> for msgProp to
 542:    *                request default QOP.
 543:    * @return The MIC.
 544:    * @throws GSSException If this operation fails.
 545:    */
 546:   byte[] getMIC(byte[] inMsg, int offset, int len, MessageProp msgProp)
 547:     throws GSSException;
 548: 
 549:   /**
 550:    * <p>Produces a token containing a cryptographic MIC for the supplied
 551:    * message, for transfer to the peer application.  Unlike wrap, which
 552:    * encapsulates the user message in the returned token, only the message
 553:    * MIC is produced in the output token.  This method is identical in
 554:    * functionality to its byte array counterpart.</p>
 555:    *
 556:    * <p>Note that privacy can only be applied through the wrap call.</p>
 557:    *
 558:    * <p>Since some application-level protocols may wish to use tokens emitted
 559:    * by getMIC to provide "secure framing", implementations should support
 560:    * derivation of MICs from zero-length messages.</p>
 561:    *
 562:    * @param inStream  Input stream containing the message to generate
 563:    *                  the MIC over.
 564:    * @param outStream Output stream to write the GSS-API output token to.
 565:    * @param msgProp   Instance of MessageProp that is used by the
 566:    *                  application to set the desired QOP.  Set the desired
 567:    *                  QOP to 0 in msgProp to request the default QOP.
 568:    *                  Alternatively pass in <code>null</code> for msgProp
 569:    *                  to request default QOP.
 570:    * @throws GSSException If this operation fails.
 571:    */
 572:   void getMIC(InputStream inStream, OutputStream outStream, MessageProp mgProp)
 573:     throws GSSException;
 574: 
 575:   /**
 576:    * <p>Verifies the cryptographic MIC, contained in the token parameter,
 577:    * over the supplied message.  This method is equivalent in
 578:    * functionality to its stream counterpart.</p>
 579:    *
 580:    * <p>The MessageProp object is instantiated by the application and is used
 581:    * by the underlying mechanism to return information to the caller such
 582:    * as the QOP indicating the strength of protection that was applied to
 583:    * the message and other supplementary message state information.</p>
 584:    *
 585:    * <p>Since some application-level protocols may wish to use tokens emitted
 586:    * by getMIC to provide "secure framing", implementations should support
 587:    * the calculation and verification of MICs over zero-length messages.</p>
 588:    *
 589:    * @param inTok     Token generated by peer's getMIC method.
 590:    * @param tokOffset The offset within the inTok where the token begins.
 591:    * @param tokLen    The length of the token within the inTok (starting at
 592:    *                  the offset).
 593:    * @param inMsg     Application message to verify the cryptographic MIC
 594:    *                  over.
 595:    * @param msgOffset The offset within the inMsg where the message begins.
 596:    * @param msgLen    The length of the message within the inMsg (starting
 597:    *                  at the offset).
 598:    * @param msgProp   Upon return from the method, this object will contain
 599:    *                  the applied QOP and supplementary information
 600:    *                  stating whether the token was a duplicate, old, out
 601:    *                  of sequence or arriving after a gap.  The
 602:    *                  confidentiality state will be set to <code>false</code>.
 603:    * @throws GSSException If this operation fails.
 604:    */
 605:   void verifyMIC(byte[] inTok, int tokOffset, int tokLen, byte[] inMsg,
 606:                  int msgOffset, int msgLen, MessageProp msgProp)
 607:     throws GSSException;
 608: 
 609:   /**
 610:    * <p>Verifies the cryptographic MIC, contained in the token parameter,
 611:    * over the supplied message.  This method is equivalent in
 612:    * functionality to its byte array counterpart.</p>
 613:    *
 614:    * <p>The MessageProp object is instantiated by the application and is used
 615:    * by the underlying mechanism to return information to the caller such
 616:    * as the QOP indicating the strength of protection that was applied to
 617:    * the message and other supplementary message state information.</p>
 618:    *
 619:    * <p>Since some application-level protocols may wish to use tokens emitted
 620:    * by getMIC to provide "secure framing", implementations should support
 621:    * the calculation and verification of MICs over zero-length messages.</p>
 622:    *
 623:    * @param tokStream Input stream containing the token generated by peer's
 624:    *                  getMIC method.
 625:    * @param msgStream Input stream containing the application message to
 626:    *                  verify the cryptographic MIC over.
 627:    * @param msgProp   Upon return from the method, this object will contain
 628:    *                  the applied QOP and supplementary information
 629:    *                  stating whether the token was a duplicate, old, out of
 630:    *                  sequence or arriving after a gap.  The confidentiality
 631:    *                  state will be set to <code>false</code>.
 632:    * @throws GSSException If this operation fails.
 633:    */
 634:   void verifyMIC(InputStream tokStream, InputStream msgStream, MessageProp msgProp)
 635:     throws GSSException;
 636: 
 637:   /**
 638:    * <p>Provided to support the sharing of work between multiple processes.
 639:    * This routine will typically be used by the context-acceptor, in an
 640:    * application where a single process receives incoming connection
 641:    * requests and accepts security contexts over them, then passes the
 642:    * established context to one or more other processes for message
 643:    * exchange.</p>
 644:    *
 645:    * <p>This method deactivates the security context and creates an
 646:    * interprocess token which, when passed to the byte array constructor
 647:    * of the GSSContext interface in another process, will re-activate the
 648:    * context in the second process.  Only a single instantiation of a
 649:    * given context may be active at any one time; a subsequent attempt by
 650:    * a context exporter to access the exported security context will fail.</p>
 651:    *
 652:    * <p>The implementation may constrain the set of processes by which the
 653:    * interprocess token may be imported, either as a function of local
 654:    * security policy, or as a result of implementation decisions.  For
 655:    * example, some implementations may constrain contexts to be passed
 656:    * only between processes that run under the same account, or which are
 657:    * part of the same process group.</p>
 658:    *
 659:    * <p>The interprocess token may contain security-sensitive information
 660:    * (for example cryptographic keys).  While mechanisms are encouraged to
 661:    * either avoid placing such sensitive information within interprocess
 662:    * tokens, or to encrypt the token before returning it to the
 663:    * application, in a typical GSS-API implementation this may not be
 664:    * possible.  Thus the application must take care to protect the
 665:    * interprocess token, and ensure that any process to which the token is
 666:    * transferred is trustworthy.</p>
 667:    *
 668:    * @return The exported context.
 669:    * @throws GSSException If this operation fails.
 670:    */
 671:   byte[] export() throws GSSException;
 672: 
 673:   /**
 674:    * <p>Sets the request state of the mutual authentication flag for the
 675:    * context.  This method is only valid before the context creation
 676:    * process begins and only for the initiator.</p>
 677:    *
 678:    * @param state Boolean representing if mutual authentication should
 679:    *              be requested during context establishment.
 680:    * @throws GSSException If this operation fails.
 681:    */
 682:   void requestMutualAuth(boolean state) throws GSSException;
 683: 
 684:   /**
 685:    * <p>Sets the request state of the replay detection service for the
 686:    * context.  This method is only valid before the context creation
 687:    * process begins and only for the initiator.</p>
 688:    *
 689:    * @param state Boolean representing if replay detection is desired
 690:    *              over the established context.
 691:    * @throws GSSException If this operation fails.
 692:    */
 693:   void requestReplayDet(boolean state) throws GSSException;
 694: 
 695:   /**
 696:    * <p>Sets the request state for the sequence checking service of the
 697:    * context.  This method is only valid before the context creation
 698:    * process begins and only for the initiator.</p>
 699:    *
 700:    * @param state Boolean representing if sequence detection is desired
 701:    *              over the established context.
 702:    * @throws GSSException If this operation fails.
 703:    */
 704:   void requestSequenceDet(boolean state) throws GSSException;
 705: 
 706:   /**
 707:    * <p>Sets the request state for the credential delegation flag for the
 708:    * context.  This method is only valid before the context creation
 709:    * process begins and only for the initiator.</p>
 710:    *
 711:    * @param state Boolean representing if credential delegation is
 712:    *              desired.
 713:    * @throws GSSException If this operation fails.
 714:    */
 715:   void requestCredDeleg(boolean state) throws GSSException;
 716: 
 717:   /**
 718:    * <p>Requests anonymous support over the context.  This method is only
 719:    * valid before the context creation process begins and only for the
 720:    * initiator.</p>
 721:    *
 722:    * @param state Boolean representing if anonymity support is requested.
 723:    * @throws GSSException If this operation fails.
 724:    */
 725:   void requestAnonymity(boolean state) throws GSSException;
 726: 
 727:   /**
 728:    * <p>Requests that confidentiality service be available over the context.
 729:    * This method is only valid before the context creation process begins
 730:    * and only for the initiator.</p>
 731:    *
 732:    * @param state Boolean indicating if confidentiality services are to
 733:    *              be requested for the context.
 734:    * @throws GSSException If this operation fails.
 735:    */
 736:   void requestConf(boolean state) throws GSSException;
 737: 
 738:   /**
 739:    * <p>Requests that integrity services be available over the context. This
 740:    * method is only valid before the context creation process begins and
 741:    * only for the initiator.</p>
 742:    *
 743:    * @param state Boolean indicating if integrity services are to be
 744:    *              requested for the context.
 745:    * @throws GSSException If this operation fails.
 746:    */
 747:   void requestInteg(boolean state) throws GSSException;
 748: 
 749:   /**
 750:    * <p>Sets the desired lifetime for the context in seconds. This method is
 751:    * only valid before the context creation process begins and only for
 752:    * the initiator. Use {@link #INDEFINITE_LIFETIME} and {@link
 753:    * #DEFAULT_LIFETIME} to request indefinite or default context lifetime.</p>
 754:    *
 755:    * @param lifetime The desired context lifetime in seconds.
 756:    * @throws GSSException If this operation fails.
 757:    */
 758:   void requestLifetime(int lifetime) throws GSSException;
 759: 
 760:   /**
 761:    * <p>Sets the channel bindings to be used during context establishment.
 762:    * This method is only valid before the context creation process begins.</p>
 763:    *
 764:    * @param cb Channel bindings to be used.
 765:    * @throws GSSException If this operation fails.
 766:    */
 767:   void setChannelBinding(ChannelBinding cb) throws GSSException;
 768: 
 769:   /**
 770:    * <p>Returns the state of the delegated credentials for the context.
 771:    * When issued before context establishment is completed or when the
 772:    * isProtReady method returns "false", it returns the desired state,
 773:    * otherwise it will indicate the actual state over the established
 774:    * context.</p>
 775:    *
 776:    * @return The state of the delegated credentials for the context.
 777:    */
 778:   boolean getCredDelegState();
 779: 
 780:   /**
 781:    * <p>Returns the state of the mutual authentication option for the
 782:    * context.  When issued before context establishment completes or when
 783:    * the isProtReady method returns "false", it returns the desired state,
 784:    * otherwise it will indicate the actual state over the established
 785:    * context.</p>
 786:    *
 787:    * @return The state of the mutual authentication option.
 788:    */
 789:   boolean getMutualAuthState();
 790: 
 791:   /**
 792:    * <p>Returns the state of the replay detection option for the context.
 793:    * When issued before context establishment completes or when the
 794:    * isProtReady method returns "false", it returns the desired state,
 795:    * otherwise it will indicate the actual state over the established
 796:    * context.</p>
 797:    *
 798:    * @return The state of the replay detection option.
 799:    */
 800:   boolean getReplayDetState();
 801: 
 802:   /**
 803:    * <p>Returns the state of the sequence detection option for the context.
 804:    * When issued before context establishment completes or when the
 805:    * isProtReady method returns "false", it returns the desired state,
 806:    * otherwise it will indicate the actual state over the established
 807:    * context.</p>
 808:    *
 809:    * @return The state of the sequence detection option.
 810:    */
 811:   boolean getSequenceDetState();
 812: 
 813:   /**
 814:    * <p>Returns "true" if this is an anonymous context. When issued before
 815:    * context establishment completes or when the isProtReady method
 816:    * returns "false", it returns the desired state, otherwise it will
 817:    * indicate the actual state over the established context.</p>
 818:    *
 819:    * @return True if this is an anonymous context.
 820:    */
 821:   boolean getAnonymityState();
 822: 
 823:   /**
 824:    * <p>Returns "true" if the context is transferable to other processes
 825:    * through the use of the {@link #export()} method. This call is only
 826:    * valid on fully established contexts.</p>
 827:    *
 828:    * @return True if the context is transferable.
 829:    * @throws GSSException If this operation fails.
 830:    */
 831:   boolean isTransferable() throws GSSException;
 832: 
 833:   /**
 834:    * <p>Returns "true" if the per message operations can be applied over
 835:    * the context.  Some mechanisms may allow the usage of per-message
 836:    * operations before the context is fully established.  This will also
 837:    * indicate that the get methods will return actual context state
 838:    * characteristics instead of the desired ones.</p>
 839:    *
 840:    * @return True if the per message operations can be applied over
 841:    *         the context.
 842:    */
 843:   boolean isProtReady();
 844: 
 845:   /**
 846:    * <p>Returns the confidentiality service state over the context. When
 847:    * issued before context establishment completes or when the isProtReady
 848:    * method returns "false", it returns the desired state, otherwise it
 849:    * will indicate the actual state over the established context.</p>
 850:    *
 851:    * @return True the confidentiality service state.
 852:    */
 853:   boolean getConfState();
 854: 
 855:   /**
 856:    * <p>Returns the integrity service state over the context. When issued
 857:    * before context establishment completes or when the isProtReady method
 858:    * returns "false", it returns the desired state, otherwise it will
 859:    * indicate the actual state over the established context.</p>
 860:    *
 861:    * @return The integrity service state.
 862:    */
 863:   boolean getIntegState();
 864: 
 865:   /**
 866:    * <p>Returns the context lifetime in seconds. When issued before context
 867:    * establishment completes or when the isProtReady method returns
 868:    * "false", it returns the desired lifetime, otherwise it will indicate
 869:    * the remaining lifetime for the context.</p>
 870:    *
 871:    * @return The lifetime.
 872:    */
 873:   int getLifetime();
 874: 
 875:   /**
 876:    * <p>Returns the name of the context initiator. This call is valid only
 877:    * after the context is fully established or the isProtReady method
 878:    * returns "true".  It is guaranteed to return an MN.</p>
 879:    *
 880:    * @return The name of the context initiator.
 881:    * @throws GSSException If this operation fails.
 882:    */
 883:   GSSName getSrcName() throws GSSException;
 884: 
 885:   /**
 886:    * <p>Returns the name of the context target (acceptor).  This call is
 887:    * valid only after the context is fully established or the isProtReady
 888:    * method returns "true".  It is guaranteed to return an MN.</p>
 889:    *
 890:    * @return The name of the context target.
 891:    * @throws GSSException If this operation fails.
 892:    */
 893:   GSSName getTargName() throws GSSException;
 894: 
 895:   /**
 896:    * <p>Returns the mechanism oid for this context. This method may be called
 897:    * before the context is fully established, but the mechanism returned
 898:    * may change on successive calls in negotiated mechanism case.</p>
 899:    *
 900:    * @return The mechanism OID.
 901:    * @throws GSSException If this operation fails.
 902:    */
 903:   Oid getMech() throws GSSException;
 904: 
 905:   /**
 906:    * <p>Returns the delegated credential object on the acceptor's side.
 907:    * To check for availability of delegated credentials call
 908:    * {@link #getDelegCredState()}. This call is only valid on fully
 909:    * established contexts.</p>
 910:    *
 911:    * @return The delegated credential object.
 912:    * @throws GSSException If this operation fails.
 913:    */
 914:   GSSCredential getDelegCred() throws GSSException;
 915: 
 916:   /**
 917:    * <p>Returns "true" if this is the initiator of the context. This call is
 918:    * only valid after the context creation process has started.</p>
 919:    *
 920:    * @return True if this is the initiator.
 921:    * @throws GSSException If this operation fails.
 922:    */
 923:   boolean isInitiator() throws GSSException;
 924: }