| Frames | No Frames |
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 mgProp 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: }