0001: /*
0002: * Copyright 2000-2001 Sun Microsystems, Inc. All Rights Reserved.
0003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004: *
0005: * This code is free software; you can redistribute it and/or modify it
0006: * under the terms of the GNU General Public License version 2 only, as
0007: * published by the Free Software Foundation. Sun designates this
0008: * particular file as subject to the "Classpath" exception as provided
0009: * by Sun in the LICENSE file that accompanied this code.
0010: *
0011: * This code is distributed in the hope that it will be useful, but WITHOUT
0012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014: * version 2 for more details (a copy is included in the LICENSE file that
0015: * accompanied this code).
0016: *
0017: * You should have received a copy of the GNU General Public License version
0018: * 2 along with this work; if not, write to the Free Software Foundation,
0019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020: *
0021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022: * CA 95054 USA or visit www.sun.com if you need additional information or
0023: * have any questions.
0024: */
0025:
0026: package org.ietf.jgss;
0027:
0028: import sun.security.jgss.spi.*;
0029: import java.io.InputStream;
0030: import java.io.OutputStream;
0031:
0032: /**
0033: * This interface encapsulates the GSS-API security context and provides
0034: * the security services that are available over the context. Security
0035: * contexts are established between peers using locally acquired
0036: * credentials. Multiple contexts may exist simultaneously between a pair
0037: * of peers, using the same or different set of credentials. GSS-API
0038: * functions in a manner independent of the underlying transport protocol
0039: * and depends on its calling application to transport the tokens that are
0040: * generated by the security context between the peers.<p>
0041: *
0042: * If the caller instantiates the context using the default
0043: * <code>GSSManager</code> instance, then the Kerberos v5 GSS-API mechanism
0044: * is guaranteed to be available for context establishment. This mechanism
0045: * is identified by the Oid "1.2.840.113554.1.2.2" and is defined in RFC
0046: * 1964.<p>
0047: *
0048: * Before the context establishment phase is initiated, the context
0049: * initiator may request specific characteristics desired of the
0050: * established context. Not all underlying mechanisms support all
0051: * characteristics that a caller might desire. After the context is
0052: * established, the caller can check the actual characteristics and services
0053: * offered by that context by means of various query methods. When using
0054: * the Kerberos v5 GSS-API mechanism offered by the default
0055: * <code>GSSManager</code> instance, all optional services will be
0056: * available locally. They are mutual authentication, credential
0057: * delegation, confidentiality and integrity protection, and per-message
0058: * replay detection and sequencing. Note that in the GSS-API, message integrity
0059: * is a prerequisite for message confidentiality.<p>
0060: *
0061: * The context establishment occurs in a loop where the
0062: * initiator calls {@link #initSecContext(byte[], int, int) initSecContext}
0063: * and the acceptor calls {@link #acceptSecContext(byte[], int, int)
0064: * acceptSecContext} until the context is established. While in this loop
0065: * the <code>initSecContext</code> and <code>acceptSecContext</code>
0066: * methods produce tokens that the application sends over to the peer. The
0067: * peer passes any such token as input to its <code>acceptSecContext</code>
0068: * or <code>initSecContext</code> as the case may be.<p>
0069: *
0070: * During the context establishment phase, the {@link
0071: * #isProtReady() isProtReady} method may be called to determine if the
0072: * context can be used for the per-message operations of {@link
0073: * #wrap(byte[], int, int, MessageProp) wrap} and {@link #getMIC(byte[],
0074: * int, int, MessageProp) getMIC}. This allows applications to use
0075: * per-message operations on contexts which aren't yet fully
0076: * established.<p>
0077: *
0078: * After the context has been established or the <code>isProtReady</code>
0079: * method returns <code>true</code>, the query routines can be invoked to
0080: * determine the actual characteristics and services of the established
0081: * context. The application can also start using the per-message methods
0082: * of {@link #wrap(byte[], int, int, MessageProp) wrap} and
0083: * {@link #getMIC(byte[], int, int, MessageProp) getMIC} to obtain
0084: * cryptographic operations on application supplied data.<p>
0085: *
0086: * When the context is no longer needed, the application should call
0087: * {@link #dispose() dispose} to release any system resources the context
0088: * may be using.<p>
0089: *
0090: * A security context typically maintains sequencing and replay detection
0091: * information about the tokens it processes. Therefore, the sequence in
0092: * which any tokens are presented to this context for processing can be
0093: * important. Also note that none of the methods in this interface are
0094: * synchronized. Therefore, it is not advisable to share a
0095: * <code>GSSContext</code> among several threads unless some application
0096: * level synchronization is in place.<p>
0097: *
0098: * Finally, different mechanism providers might place different security
0099: * restrictions on using GSS-API contexts. These will be documented by the
0100: * mechanism provider. The application will need to ensure that it has the
0101: * appropriate permissions if such checks are made in the mechanism layer.<p>
0102: *
0103: * The example code presented below demonstrates the usage of the
0104: * <code>GSSContext</code> interface for the initiating peer. Different
0105: * operations on the <code>GSSContext</code> object are presented,
0106: * including: object instantiation, setting of desired flags, context
0107: * establishment, query of actual context flags, per-message operations on
0108: * application data, and finally context deletion.<p>
0109: *
0110: * <pre>
0111: * // Create a context using default credentials
0112: * // and the implementation specific default mechanism
0113: * GSSManager manager ...
0114: * GSSName targetName ...
0115: * GSSContext context = manager.createContext(targetName, null, null,
0116: * GSSContext.INDEFINITE_LIFETIME);
0117: *
0118: * // set desired context options prior to context establishment
0119: * context.requestConf(true);
0120: * context.requestMutualAuth(true);
0121: * context.requestReplayDet(true);
0122: * context.requestSequenceDet(true);
0123: *
0124: * // establish a context between peers
0125: *
0126: * byte []inToken = new byte[0];
0127: *
0128: * // Loop while there still is a token to be processed
0129: *
0130: * while (!context.isEstablished()) {
0131: *
0132: * byte[] outToken
0133: * = context.initSecContext(inToken, 0, inToken.length);
0134: *
0135: * // send the output token if generated
0136: * if (outToken != null)
0137: * sendToken(outToken);
0138: *
0139: * if (!context.isEstablished()) {
0140: * inToken = readToken();
0141: * }
0142: *
0143: * // display context information
0144: * System.out.println("Remaining lifetime in seconds = "
0145: * + context.getLifetime());
0146: * System.out.println("Context mechanism = " + context.getMech());
0147: * System.out.println("Initiator = " + context.getSrcName());
0148: * System.out.println("Acceptor = " + context.getTargName());
0149: *
0150: * if (context.getConfState())
0151: * System.out.println("Confidentiality (i.e., privacy) is available");
0152: *
0153: * if (context.getIntegState())
0154: * System.out.println("Integrity is available");
0155: *
0156: * // perform wrap on an application supplied message, appMsg,
0157: * // using QOP = 0, and requesting privacy service
0158: * byte [] appMsg ...
0159: *
0160: * MessageProp mProp = new MessageProp(0, true);
0161: *
0162: * byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp);
0163: *
0164: * sendToken(tok);
0165: *
0166: * // release the local-end of the context
0167: * context.dispose();
0168: *
0169: * </pre>
0170: *
0171: * @author Mayank Upadhyay
0172: * @version 1.17, 05/05/07
0173: * @since 1.4
0174: */
0175: public interface GSSContext {
0176:
0177: /**
0178: * A lifetime constant representing the default context lifetime. This
0179: * value is set to 0.
0180: */
0181: public static final int DEFAULT_LIFETIME = 0;
0182:
0183: /**
0184: * A lifetime constant representing indefinite context lifetime.
0185: * This value must is set to the maximum integer value in Java -
0186: * {@link java.lang.Integer#MAX_VALUE Integer.MAX_VALUE}.
0187: */
0188: public static final int INDEFINITE_LIFETIME = Integer.MAX_VALUE;
0189:
0190: /**
0191: * Called by the context initiator to start the context creation
0192: * phase and process any tokens generated
0193: * by the peer's <code>acceptSecContext</code> method.
0194: * This method may return an output token which the application will need
0195: * to send to the peer for processing by its <code>acceptSecContext</code>
0196: * method. The application can call {@link #isEstablished()
0197: * isEstablished} to determine if the context establishment phase is
0198: * complete on this side of the context. A return value of
0199: * <code>false</code> from <code>isEstablished</code> indicates that
0200: * more tokens are expected to be supplied to
0201: * <code>initSecContext</code>. Upon completion of the context
0202: * establishment, the available context options may be queried through
0203: * the get methods.<p>
0204: *
0205: * Note that it is possible that the <code>initSecContext</code> method
0206: * return a token for the peer, and <code>isEstablished</code> return
0207: * <code>true</code> also. This indicates that the token needs to be sent
0208: * to the peer, but the local end of the context is now fully
0209: * established.<p>
0210: *
0211: * Some mechanism providers might require that the caller be granted
0212: * permission to initiate a security context. A failed permission check
0213: * might cause a {@link java.lang.SecurityException SecurityException}
0214: * to be thrown from this method.<p>
0215: *
0216: * @return a byte[] containing the token to be sent to the
0217: * peer. <code>null</code> indicates that no token is generated.
0218: * @param inputBuf token generated by the peer. This parameter is ignored
0219: * on the first call since no token has been received from the peer.
0220: * @param offset the offset within the inputBuf where the token begins.
0221: * @param len the length of the token.
0222: *
0223: * @throws GSSException containing the following
0224: * major error codes:
0225: * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
0226: * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
0227: * {@link GSSException#NO_CRED GSSException.NO_CRED},
0228: * {@link GSSException#CREDENTIALS_EXPIRED
0229: * GSSException.CREDENTIALS_EXPIRED},
0230: * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
0231: * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
0232: * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
0233: * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
0234: * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
0235: * {@link GSSException#FAILURE GSSException.FAILURE}
0236: */
0237: public byte[] initSecContext(byte inputBuf[], int offset, int len)
0238: throws GSSException;
0239:
0240: /**
0241: * Called by the context initiator to start the context creation
0242: * phase and process any tokens generated
0243: * by the peer's <code>acceptSecContext</code> method using
0244: * streams. This method may write an output token to the
0245: * <code>OutpuStream</code>, which the application will
0246: * need to send to the peer for processing by its
0247: * <code>acceptSecContext</code> call. Typically, the application would
0248: * ensure this by calling the {@link java.io.OutputStream#flush() flush}
0249: * method on an <code>OutputStream</code> that encapsulates the
0250: * connection between the two peers. The application can
0251: * determine if a token is written to the OutputStream from the return
0252: * value of this method. A return value of <code>0</code> indicates that
0253: * no token was written. The application can call
0254: * {@link #isEstablished() isEstablished} to determine if the context
0255: * establishment phase is complete on this side of the context. A
0256: * return value of <code>false</code> from <code>isEstablished</code>
0257: * indicates that more tokens are expected to be supplied to
0258: * <code>initSecContext</code>.
0259: * Upon completion of the context establishment, the available context
0260: * options may be queried through the get methods.<p>
0261: *
0262: * Note that it is possible that the <code>initSecContext</code> method
0263: * return a token for the peer, and <code>isEstablished</code> return
0264: * <code>true</code> also. This indicates that the token needs to be sent
0265: * to the peer, but the local end of the context is now fully
0266: * established.<p>
0267: *
0268: * The GSS-API authentication tokens contain a definitive start and
0269: * end. This method will attempt to read one of these tokens per
0270: * invocation, and may block on the stream if only part of the token is
0271: * available. In all other respects this method is equivalent to the
0272: * byte array based {@link #initSecContext(byte[], int, int)
0273: * initSecContext}.<p>
0274: *
0275: * Some mechanism providers might require that the caller be granted
0276: * permission to initiate a security context. A failed permission check
0277: * might cause a {@link java.lang.SecurityException SecurityException}
0278: * to be thrown from this method.<p>
0279: *
0280: * The following example code demonstrates how this method might be
0281: * used:<p>
0282: * <pre>
0283: * InputStream is ...
0284: * OutputStream os ...
0285: * GSSContext context ...
0286: *
0287: * // Loop while there is still a token to be processed
0288: *
0289: * while (!context.isEstablished()) {
0290: *
0291: * context.initSecContext(is, os);
0292: *
0293: * // send output token if generated
0294: * os.flush();
0295: * }
0296: * </pre>
0297: *
0298: *
0299: * @return the number of bytes written to the OutputStream as part of the
0300: * token to be sent to the peer. A value of 0 indicates that no token
0301: * needs to be sent.
0302: * @param inStream an InputStream that contains the token generated by
0303: * the peer. This parameter is ignored on the first call since no token
0304: * has been or will be received from the peer at that point.
0305: * @param outStream an OutputStream where the output token will be
0306: * written. During the final stage of context establishment, there may be
0307: * no bytes written.
0308: *
0309: * @throws GSSException containing the following
0310: * major error codes:
0311: * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
0312: * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
0313: * {@link GSSException#NO_CRED GSSException.NO_CRED},
0314: * {@link GSSException#CREDENTIALS_EXPIRED GSSException.CREDENTIALS_EXPIRED},
0315: * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
0316: * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
0317: * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
0318: * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
0319: * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
0320: * {@link GSSException#FAILURE GSSException.FAILURE}
0321: */
0322: public int initSecContext(InputStream inStream,
0323: OutputStream outStream) throws GSSException;
0324:
0325: /**
0326: * Called by the context acceptor upon receiving a token from the
0327: * peer. This method may return an output token which the application
0328: * will need to send to the peer for further processing by its
0329: * <code>initSecContext</code> call.<p>
0330: *
0331: * The application can call {@link #isEstablished() isEstablished} to
0332: * determine if the context establishment phase is complete for this
0333: * peer. A return value of <code>false</code> from
0334: * <code>isEstablished</code> indicates that more tokens are expected to
0335: * be supplied to this method. Upon completion of the context
0336: * establishment, the available context options may be queried through
0337: * the get methods.<p>
0338: *
0339: * Note that it is possible that <code>acceptSecContext</code> return a
0340: * token for the peer, and <code>isEstablished</code> return
0341: * <code>true</code> also. This indicates that the token needs to be
0342: * sent to the peer, but the local end of the context is now fully
0343: * established.<p>
0344: *
0345: * Some mechanism providers might require that the caller be granted
0346: * permission to accept a security context. A failed permission check
0347: * might cause a {@link java.lang.SecurityException SecurityException}
0348: * to be thrown from this method.<p>
0349: *
0350: * The following example code demonstrates how this method might be
0351: * used:<p>
0352: * <pre>
0353: * byte[] inToken;
0354: * byte[] outToken;
0355: * GSSContext context ...
0356: *
0357: * // Loop while there is still a token to be processed
0358: *
0359: * while (!context.isEstablished()) {
0360: * inToken = readToken();
0361: * outToken = context.acceptSecContext(inToken, 0,
0362: * inToken.length);
0363: * // send output token if generated
0364: * if (outToken != null)
0365: * sendToken(outToken);
0366: * }
0367: * </pre>
0368: *
0369: *
0370: * @return a byte[] containing the token to be sent to the
0371: * peer. <code>null</code> indicates that no token is generated.
0372: * @param inToken token generated by the peer.
0373: * @param offset the offset within the inToken where the token begins.
0374: * @param len the length of the token.
0375: *
0376: * @throws GSSException containing the following
0377: * major error codes:
0378: * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
0379: * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
0380: * {@link GSSException#NO_CRED GSSException.NO_CRED},
0381: * {@link GSSException#CREDENTIALS_EXPIRED
0382: * GSSException.CREDENTIALS_EXPIRED},
0383: * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
0384: * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
0385: * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
0386: * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
0387: * {@link GSSException#FAILURE GSSException.FAILURE}
0388: */
0389: public byte[] acceptSecContext(byte inToken[], int offset, int len)
0390: throws GSSException;
0391:
0392: /**
0393: * Called by the context acceptor to process a token from the peer using
0394: * streams. It may write an output token to the
0395: * <code>OutputStream</code>, which the application
0396: * will need to send to the peer for processing by its
0397: * <code>initSecContext</code> method. Typically, the application would
0398: * ensure this by calling the {@link java.io.OutputStream#flush() flush}
0399: * method on an <code>OutputStream</code> that encapsulates the
0400: * connection between the two peers. The application can call
0401: * {@link #isEstablished() isEstablished} to determine if the context
0402: * establishment phase is complete on this side of the context. A
0403: * return value of <code>false</code> from <code>isEstablished</code>
0404: * indicates that more tokens are expected to be supplied to
0405: * <code>acceptSecContext</code>.
0406: * Upon completion of the context establishment, the available context
0407: * options may be queried through the get methods.<p>
0408: *
0409: * Note that it is possible that <code>acceptSecContext</code> return a
0410: * token for the peer, and <code>isEstablished</code> return
0411: * <code>true</code> also. This indicates that the token needs to be
0412: * sent to the peer, but the local end of the context is now fully
0413: * established.<p>
0414: *
0415: * The GSS-API authentication tokens contain a definitive start and
0416: * end. This method will attempt to read one of these tokens per
0417: * invocation, and may block on the stream if only part of the token is
0418: * available. In all other respects this method is equivalent to the byte
0419: * array based {@link #acceptSecContext(byte[], int, int)
0420: * acceptSecContext}.<p>
0421: *
0422: * Some mechanism providers might require that the caller be granted
0423: * permission to accept a security context. A failed permission check
0424: * might cause a {@link java.lang.SecurityException SecurityException}
0425: * to be thrown from this method.<p>
0426: *
0427: * The following example code demonstrates how this method might be
0428: * used:<p>
0429: * <pre>
0430: * InputStream is ...
0431: * OutputStream os ...
0432: * GSSContext context ...
0433: *
0434: * // Loop while there is still a token to be processed
0435: *
0436: * while (!context.isEstablished()) {
0437: *
0438: * context.acceptSecContext(is, os);
0439: *
0440: * // send output token if generated
0441: * os.flush();
0442: * }
0443: * </pre>
0444: *
0445: *
0446: * @param inStream an InputStream that contains the token generated by
0447: * the peer.
0448: * @param outStream an OutputStream where the output token will be
0449: * written. During the final stage of context establishment, there may be
0450: * no bytes written.
0451: *
0452: * @throws GSSException containing the following
0453: * major error codes:
0454: * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
0455: * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
0456: * {@link GSSException#NO_CRED GSSException.NO_CRED},
0457: * {@link GSSException#CREDENTIALS_EXPIRED
0458: * GSSException.CREDENTIALS_EXPIRED},
0459: * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
0460: * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
0461: * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
0462: * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
0463: * {@link GSSException#FAILURE GSSException.FAILURE}
0464: */
0465: /* Missing return value in RFC. int should have been returned.
0466: * -----------------------------------------------------------
0467: *
0468: * The application can determine if a token is written to the
0469: * OutputStream from the return value of this method. A return value of
0470: * <code>0</code> indicates that no token was written.
0471: *
0472: * @return <strong>the number of bytes written to the
0473: * OutputStream as part of the token to be sent to the peer. A value of
0474: * 0 indicates that no token needs to be
0475: * sent.</strong>
0476: */
0477: public void acceptSecContext(InputStream inStream,
0478: OutputStream outStream) throws GSSException;
0479:
0480: /**
0481: * Used during context establishment to determine the state of the
0482: * context.
0483: *
0484: * @return <code>true</code> if this is a fully established context on
0485: * the caller's side and no more tokens are needed from the peer.
0486: */
0487: public boolean isEstablished();
0488:
0489: /**
0490: * Releases any system resources and cryptographic information stored in
0491: * the context object and invalidates the context.
0492: *
0493: *
0494: * @throws GSSException containing the following
0495: * major error codes:
0496: * {@link GSSException#FAILURE GSSException.FAILURE}
0497: */
0498: public void dispose() throws GSSException;
0499:
0500: /**
0501: * Used to determine limits on the size of the message
0502: * that can be passed to <code>wrap</code>. Returns the maximum
0503: * message size that, if presented to the <code>wrap</code> method with
0504: * the same <code>confReq</code> and <code>qop</code> parameters, will
0505: * result in an output token containing no more
0506: * than <code>maxTokenSize</code> bytes.<p>
0507: *
0508: * This call is intended for use by applications that communicate over
0509: * protocols that impose a maximum message size. It enables the
0510: * application to fragment messages prior to applying protection.<p>
0511: *
0512: * GSS-API implementations are recommended but not required to detect
0513: * invalid QOP values when <code>getWrapSizeLimit</code> is called.
0514: * This routine guarantees only a maximum message size, not the
0515: * availability of specific QOP values for message protection.<p>
0516: *
0517: * @param qop the level of protection wrap will be asked to provide.
0518: * @param confReq <code>true</code> if wrap will be asked to provide
0519: * privacy, <code>false</code> otherwise.
0520: * @param maxTokenSize the desired maximum size of the token emitted by
0521: * wrap.
0522: * @return the maximum size of the input token for the given output
0523: * token size
0524: *
0525: * @throws GSSException containing the following
0526: * major error codes:
0527: * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
0528: * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
0529: * {@link GSSException#FAILURE GSSException.FAILURE}
0530: */
0531: public int getWrapSizeLimit(int qop, boolean confReq,
0532: int maxTokenSize) throws GSSException;
0533:
0534: /**
0535: * Applies per-message security services over the established security
0536: * context. The method will return a token with the
0537: * application supplied data and a cryptographic MIC over it.
0538: * The data may be encrypted if confidentiality (privacy) was
0539: * requested.<p>
0540: *
0541: * The MessageProp object is instantiated by the application and used
0542: * to specify a QOP value which selects cryptographic algorithms, and a
0543: * privacy service to optionally encrypt the message. The underlying
0544: * mechanism that is used in the call may not be able to provide the
0545: * privacy service. It sets the actual privacy service that it does
0546: * provide in this MessageProp object which the caller should then
0547: * query upon return. If the mechanism is not able to provide the
0548: * requested QOP, it throws a GSSException with the BAD_QOP code.<p>
0549: *
0550: * Since some application-level protocols may wish to use tokens
0551: * emitted by wrap to provide "secure framing", implementations should
0552: * support the wrapping of zero-length messages.<p>
0553: *
0554: * The application will be responsible for sending the token to the
0555: * peer.
0556: *
0557: * @param inBuf application data to be protected.
0558: * @param offset the offset within the inBuf where the data begins.
0559: * @param len the length of the data
0560: * @param msgProp instance of MessageProp that is used by the
0561: * application to set the desired QOP and privacy state. Set the
0562: * desired QOP to 0 to request the default QOP. Upon return from this
0563: * method, this object will contain the the actual privacy state that
0564: * was applied to the message by the underlying mechanism.
0565: * @return a byte[] containing the token to be sent to the peer.
0566: *
0567: * @throws GSSException containing the following major error codes:
0568: * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
0569: * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
0570: * {@link GSSException#FAILURE GSSException.FAILURE}
0571: */
0572: public byte[] wrap(byte inBuf[], int offset, int len,
0573: MessageProp msgProp) throws GSSException;
0574:
0575: /**
0576: * Applies per-message security services over the established security
0577: * context using streams. The method will return a
0578: * token with the application supplied data and a cryptographic MIC over it.
0579: * The data may be encrypted if confidentiality
0580: * (privacy) was requested. This method is equivalent to the byte array
0581: * based {@link #wrap(byte[], int, int, MessageProp) wrap} method.<p>
0582: *
0583: * The application will be responsible for sending the token to the
0584: * peer. Typically, the application would
0585: * ensure this by calling the {@link java.io.OutputStream#flush() flush}
0586: * method on an <code>OutputStream</code> that encapsulates the
0587: * connection between the two peers.<p>
0588: *
0589: * The MessageProp object is instantiated by the application and used
0590: * to specify a QOP value which selects cryptographic algorithms, and a
0591: * privacy service to optionally encrypt the message. The underlying
0592: * mechanism that is used in the call may not be able to provide the
0593: * privacy service. It sets the actual privacy service that it does
0594: * provide in this MessageProp object which the caller should then
0595: * query upon return. If the mechanism is not able to provide the
0596: * requested QOP, it throws a GSSException with the BAD_QOP code.<p>
0597: *
0598: * Since some application-level protocols may wish to use tokens
0599: * emitted by wrap to provide "secure framing", implementations should
0600: * support the wrapping of zero-length messages.<p>
0601: *
0602: * @param inStream an InputStream containing the application data to be
0603: * protected. All of the data that is available in
0604: * inStream is used.
0605: * @param outStream an OutputStream to write the protected message
0606: * to.
0607: * @param msgProp instance of MessageProp that is used by the
0608: * application to set the desired QOP and privacy state. Set the
0609: * desired QOP to 0 to request the default QOP. Upon return from this
0610: * method, this object will contain the the actual privacy state that
0611: * was applied to the message by the underlying mechanism.
0612: *
0613: * @throws GSSException containing the following
0614: * major error codes:
0615: * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
0616: * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
0617: * {@link GSSException#FAILURE GSSException.FAILURE}
0618: */
0619: public void wrap(InputStream inStream, OutputStream outStream,
0620: MessageProp msgProp) throws GSSException;
0621:
0622: /**
0623: * Used to process tokens generated by the <code>wrap</code> method on
0624: * the other side of the context. The method will return the message
0625: * supplied by the peer application to its wrap call, while at the same
0626: * time verifying the embedded MIC for that message.<p>
0627: *
0628: * The MessageProp object is instantiated by the application and is
0629: * used by the underlying mechanism to return information to the caller
0630: * such as the QOP, whether confidentiality was applied to the message,
0631: * and other supplementary message state information.<p>
0632: *
0633: * Since some application-level protocols may wish to use tokens
0634: * emitted by wrap to provide "secure framing", implementations should
0635: * support the wrapping and unwrapping of zero-length messages.<p>
0636: *
0637: * @param inBuf a byte array containing the wrap token received from
0638: * peer.
0639: * @param offset the offset where the token begins.
0640: * @param len the length of the token
0641: * @param msgProp upon return from the method, this object will contain
0642: * the applied QOP, the privacy state of the message, and supplementary
0643: * information stating if the token was a duplicate, old, out of
0644: * sequence or arriving after a gap.
0645: * @return a byte[] containing the message unwrapped from the input
0646: * token.
0647: *
0648: * @throws GSSException containing the following
0649: * major error codes:
0650: * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
0651: * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
0652: * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
0653: * {@link GSSException#FAILURE GSSException.FAILURE}
0654: */
0655: public byte[] unwrap(byte[] inBuf, int offset, int len,
0656: MessageProp msgProp) throws GSSException;
0657:
0658: /**
0659: * Uses streams to process tokens generated by the <code>wrap</code>
0660: * method on the other side of the context. The method will return the
0661: * message supplied by the peer application to its wrap call, while at
0662: * the same time verifying the embedded MIC for that message.<p>
0663: *
0664: * The MessageProp object is instantiated by the application and is
0665: * used by the underlying mechanism to return information to the caller
0666: * such as the QOP, whether confidentiality was applied to the message,
0667: * and other supplementary message state information.<p>
0668: *
0669: * Since some application-level protocols may wish to use tokens
0670: * emitted by wrap to provide "secure framing", implementations should
0671: * support the wrapping and unwrapping of zero-length messages.<p>
0672: *
0673: * The format of the input token that this method
0674: * reads is defined in the specification for the underlying mechanism that
0675: * will be used. This method will attempt to read one of these tokens per
0676: * invocation. If the mechanism token contains a definitive start and
0677: * end this method may block on the <code>InputStream</code> if only
0678: * part of the token is available. If the start and end of the token
0679: * are not definitive then the method will attempt to treat all
0680: * available bytes as part of the token.<p>
0681: *
0682: * Other than the possible blocking behaviour described above, this
0683: * method is equivalent to the byte array based {@link #unwrap(byte[],
0684: * int, int, MessageProp) unwrap} method.<p>
0685: *
0686: * @param inStream an InputStream that contains the wrap token generated
0687: * by the peer.
0688: * @param outStream an OutputStream to write the application message
0689: * to.
0690: * @param msgProp upon return from the method, this object will contain
0691: * the applied QOP, the privacy state of the message, and supplementary
0692: * information stating if the token was a duplicate, old, out of
0693: * sequence or arriving after a gap.
0694: *
0695: * @throws GSSException containing the following
0696: * major error codes:
0697: * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
0698: * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
0699: * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
0700: * {@link GSSException#FAILURE GSSException.FAILURE}
0701: */
0702: public void unwrap(InputStream inStream, OutputStream outStream,
0703: MessageProp msgProp) throws GSSException;
0704:
0705: /**
0706: * Returns a token containing a cryptographic Message Integrity Code
0707: * (MIC) for the supplied message, for transfer to the peer
0708: * application. Unlike wrap, which encapsulates the user message in the
0709: * returned token, only the message MIC is returned in the output
0710: * token.<p>
0711: *
0712: * Note that privacy can only be applied through the wrap call.<p>
0713: *
0714: * Since some application-level protocols may wish to use tokens emitted
0715: * by getMIC to provide "secure framing", implementations should support
0716: * derivation of MICs from zero-length messages.
0717: *
0718: * @param inMsg the message to generate the MIC over.
0719: * @param offset offset within the inMsg where the message begins.
0720: * @param len the length of the message
0721: * @param msgProp an instance of <code>MessageProp</code> that is used
0722: * by the application to set the desired QOP. Set the desired QOP to
0723: * <code>0</code> in <code>msgProp</code> to request the default
0724: * QOP. Alternatively pass in <code>null</code> for <code>msgProp</code>
0725: * to request the default QOP.
0726: * @return a byte[] containing the token to be sent to the peer.
0727: *
0728: * @throws GSSException containing the following
0729: * major error codes:
0730: * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
0731: * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
0732: * {@link GSSException#FAILURE GSSException.FAILURE}
0733: */
0734: public byte[] getMIC(byte[] inMsg, int offset, int len,
0735: MessageProp msgProp) throws GSSException;
0736:
0737: /**
0738: * Uses streams to produce a token containing a cryptographic MIC for
0739: * the supplied message, for transfer to the peer application.
0740: * Unlike wrap, which encapsulates the user message in the returned
0741: * token, only the message MIC is produced in the output token. This
0742: * method is equivalent to the byte array based {@link #getMIC(byte[],
0743: * int, int, MessageProp) getMIC} method.
0744: *
0745: * Note that privacy can only be applied through the wrap call.<p>
0746: *
0747: * Since some application-level protocols may wish to use tokens emitted
0748: * by getMIC to provide "secure framing", implementations should support
0749: * derivation of MICs from zero-length messages.
0750: *
0751: * @param inStream an InputStream containing the message to generate the
0752: * MIC over. All of the data that is available in
0753: * inStream is used.
0754: * @param outStream an OutputStream to write the output token to.
0755: * @param msgProp an instance of <code>MessageProp</code> that is used
0756: * by the application to set the desired QOP. Set the desired QOP to
0757: * <code>0</code> in <code>msgProp</code> to request the default
0758: * QOP. Alternatively pass in <code>null</code> for <code>msgProp</code>
0759: * to request the default QOP.
0760: *
0761: * @throws GSSException containing the following
0762: * major error codes:
0763: * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
0764: * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
0765: * {@link GSSException#FAILURE GSSException.FAILURE}
0766: */
0767: public void getMIC(InputStream inStream, OutputStream outStream,
0768: MessageProp msgProp) throws GSSException;
0769:
0770: /**
0771: * Verifies the cryptographic MIC, contained in the token parameter,
0772: * over the supplied message.<p>
0773: *
0774: * The MessageProp object is instantiated by the application and is used
0775: * by the underlying mechanism to return information to the caller such
0776: * as the QOP indicating the strength of protection that was applied to
0777: * the message and other supplementary message state information.<p>
0778: *
0779: * Since some application-level protocols may wish to use tokens emitted
0780: * by getMIC to provide "secure framing", implementations should support
0781: * the calculation and verification of MICs over zero-length messages.
0782: *
0783: * @param inToken the token generated by peer's getMIC method.
0784: * @param tokOffset the offset within the inToken where the token
0785: * begins.
0786: * @param tokLen the length of the token.
0787: * @param inMsg the application message to verify the cryptographic MIC
0788: * over.
0789: * @param msgOffset the offset in inMsg where the message begins.
0790: * @param msgLen the length of the message.
0791: * @param msgProp upon return from the method, this object will contain
0792: * the applied QOP and supplementary information stating if the token
0793: * was a duplicate, old, out of sequence or arriving after a gap.
0794: *
0795: * @throws GSSException containing the following
0796: * major error codes:
0797: * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}
0798: * {@link GSSException#BAD_MIC GSSException.BAD_MIC}
0799: * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}
0800: * {@link GSSException#FAILURE GSSException.FAILURE}
0801: */
0802: public void verifyMIC(byte[] inToken, int tokOffset, int tokLen,
0803: byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp)
0804: throws GSSException;
0805:
0806: /**
0807: * Uses streams to verify the cryptographic MIC, contained in the token
0808: * parameter, over the supplied message. This method is equivalent to
0809: * the byte array based {@link #verifyMIC(byte[], int, int, byte[], int,
0810: * int, MessageProp) verifyMIC} method.
0811: *
0812: * The MessageProp object is instantiated by the application and is used
0813: * by the underlying mechanism to return information to the caller such
0814: * as the QOP indicating the strength of protection that was applied to
0815: * the message and other supplementary message state information.<p>
0816: *
0817: * Since some application-level protocols may wish to use tokens emitted
0818: * by getMIC to provide "secure framing", implementations should support
0819: * the calculation and verification of MICs over zero-length messages.<p>
0820: *
0821: * The format of the input token that this method
0822: * reads is defined in the specification for the underlying mechanism that
0823: * will be used. This method will attempt to read one of these tokens per
0824: * invocation. If the mechanism token contains a definitive start and
0825: * end this method may block on the <code>InputStream</code> if only
0826: * part of the token is available. If the start and end of the token
0827: * are not definitive then the method will attempt to treat all
0828: * available bytes as part of the token.<p>
0829: *
0830: * Other than the possible blocking behaviour described above, this
0831: * method is equivalent to the byte array based {@link #verifyMIC(byte[],
0832: * int, int, byte[], int, int, MessageProp) verifyMIC} method.<p>
0833: *
0834: * @param tokStream an InputStream containing the token generated by the
0835: * peer's getMIC method.
0836: * @param msgStream an InputStream containing the application message to
0837: * verify the cryptographic MIC over. All of the data
0838: * that is available in msgStream is used.
0839: * @param msgProp upon return from the method, this object will contain
0840: * the applied QOP and supplementary information stating if the token
0841: * was a duplicate, old, out of sequence or arriving after a gap.
0842: *
0843: * @throws GSSException containing the following
0844: * major error codes:
0845: * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}
0846: * {@link GSSException#BAD_MIC GSSException.BAD_MIC}
0847: * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}
0848: * {@link GSSException#FAILURE GSSException.FAILURE}
0849: */
0850: public void verifyMIC(InputStream tokStream, InputStream msgStream,
0851: MessageProp msgProp) throws GSSException;
0852:
0853: /**
0854: * Exports this context so that another process may
0855: * import it.. Provided to support the sharing of work between
0856: * multiple processes. This routine will typically be used by the
0857: * context-acceptor, in an application where a single process receives
0858: * incoming connection requests and accepts security contexts over
0859: * them, then passes the established context to one or more other
0860: * processes for message exchange.<p>
0861: *
0862: * This method deactivates the security context and creates an
0863: * interprocess token which, when passed to {@link
0864: * GSSManager#createContext(byte[]) GSSManager.createContext} in
0865: * another process, will re-activate the context in the second process.
0866: * Only a single instantiation of a given context may be active at any
0867: * one time; a subsequent attempt by a context exporter to access the
0868: * exported security context will fail.<p>
0869: *
0870: * The implementation may constrain the set of processes by which the
0871: * interprocess token may be imported, either as a function of local
0872: * security policy, or as a result of implementation decisions. For
0873: * example, some implementations may constrain contexts to be passed
0874: * only between processes that run under the same account, or which are
0875: * part of the same process group.<p>
0876: *
0877: * The interprocess token may contain security-sensitive information
0878: * (for example cryptographic keys). While mechanisms are encouraged
0879: * to either avoid placing such sensitive information within
0880: * interprocess tokens, or to encrypt the token before returning it to
0881: * the application, in a typical GSS-API implementation this may not be
0882: * possible. Thus the application must take care to protect the
0883: * interprocess token, and ensure that any process to which the token
0884: * is transferred is trustworthy. <p>
0885: *
0886: * Implementations are not required to support the inter-process
0887: * transfer of security contexts. Calling the {@link #isTransferable()
0888: * isTransferable} method will indicate if the context object is
0889: * transferable.<p>
0890: *
0891: * Calling this method on a context that
0892: * is not exportable will result in this exception being thrown with
0893: * the error code {@link GSSException#UNAVAILABLE
0894: * GSSException.UNAVAILABLE}.
0895: *
0896: * @return a byte[] containing the exported context
0897: * @see GSSManager#createContext(byte[])
0898: *
0899: * @throws GSSException containing the following
0900: * major error codes:
0901: * {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE},
0902: * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
0903: * {@link GSSException#NO_CONTEXT GSSException.NO_CONTEXT},
0904: * {@link GSSException#FAILURE GSSException.FAILURE}
0905: */
0906: public byte[] export() throws GSSException;
0907:
0908: /**
0909: * Requests that mutual authentication be done during
0910: * context establishment. This request can only be made on the context
0911: * initiator's side and it has to be done prior to the first call to
0912: * <code>initSecContext</code>.<p>
0913: *
0914: * Not all mechanisms support mutual authentication and some mechanisms
0915: * might require mutual authentication even if the application
0916: * doesn't. Therefore, the application should check to see if the
0917: * request was honored with the {@link #getMutualAuthState()
0918: * getMutualAuthState} method.<p>
0919: *
0920: * @param state a boolean value indicating whether mutual
0921: * authentication shouls be used or not.
0922: * @see #getMutualAuthState()
0923: *
0924: * @throws GSSException containing the following
0925: * major error codes:
0926: * {@link GSSException#FAILURE GSSException.FAILURE}
0927: */
0928: public void requestMutualAuth(boolean state) throws GSSException;
0929:
0930: /**
0931: * Requests that replay detection be enabled for the
0932: * per-message security services after context establishemnt. This
0933: * request can only be made on the context initiator's side and it has
0934: * to be done prior to the first call to
0935: * <code>initSecContext</code>. During context establishment replay
0936: * detection is not an option and is a function of the underlying
0937: * mechanism's capabilities.<p>
0938: *
0939: * Not all mechanisms support replay detection and some mechanisms
0940: * might require replay detection even if the application
0941: * doesn't. Therefore, the application should check to see if the
0942: * request was honored with the {@link #getReplayDetState()
0943: * getReplayDetState} method. If replay detection is enabled then the
0944: * {@link MessageProp#isDuplicateToken() MessageProp.isDuplicateToken} and {@link
0945: * MessageProp#isOldToken() MessageProp.isOldToken} methods will return
0946: * valid results for the <code>MessageProp</code> object that is passed
0947: * in to the <code>unwrap</code> method or the <code>verifyMIC</code>
0948: * method.<p>
0949: *
0950: * @param state a boolean value indicating whether replay detection
0951: * should be enabled over the established context or not.
0952: * @see #getReplayDetState()
0953: *
0954: * @throws GSSException containing the following
0955: * major error codes:
0956: * {@link GSSException#FAILURE GSSException.FAILURE}
0957: */
0958: public void requestReplayDet(boolean state) throws GSSException;
0959:
0960: /**
0961: * Requests that sequence checking be enabled for the
0962: * per-message security services after context establishemnt. This
0963: * request can only be made on the context initiator's side and it has
0964: * to be done prior to the first call to
0965: * <code>initSecContext</code>. During context establishment sequence
0966: * checking is not an option and is a function of the underlying
0967: * mechanism's capabilities.<p>
0968: *
0969: * Not all mechanisms support sequence checking and some mechanisms
0970: * might require sequence checking even if the application
0971: * doesn't. Therefore, the application should check to see if the
0972: * request was honored with the {@link #getSequenceDetState()
0973: * getSequenceDetState} method. If sequence checking is enabled then the
0974: * {@link MessageProp#isDuplicateToken() MessageProp.isDuplicateToken},
0975: * {@link MessageProp#isOldToken() MessageProp.isOldToken},
0976: * {@link MessageProp#isUnseqToken() MessageProp.isUnseqToken}, and
0977: * {@link MessageProp#isGapToken() MessageProp.isGapToken} methods will return
0978: * valid results for the <code>MessageProp</code> object that is passed
0979: * in to the <code>unwrap</code> method or the <code>verifyMIC</code>
0980: * method.<p>
0981: *
0982: * @param state a boolean value indicating whether sequence checking
0983: * should be enabled over the established context or not.
0984: * @see #getSequenceDetState()
0985: *
0986: * @throws GSSException containing the following
0987: * major error codes:
0988: * {@link GSSException#FAILURE GSSException.FAILURE}
0989: */
0990: public void requestSequenceDet(boolean state) throws GSSException;
0991:
0992: /**
0993: * Requests that the initiator's credentials be
0994: * delegated to the acceptor during context establishment. This
0995: * request can only be made on the context initiator's side and it has
0996: * to be done prior to the first call to
0997: * <code>initSecContext</code>.
0998: *
0999: * Not all mechanisms support credential delegation. Therefore, an
1000: * application that desires delegation should check to see if the
1001: * request was honored with the {@link #getCredDelegState()
1002: * getCredDelegState} method. If the application indicates that
1003: * delegation must not be used, then the mechanism will honor the
1004: * request and delegation will not occur. This is an exception
1005: * to the general rule that a mechanism may enable a service even if it
1006: * is not requested.<p>
1007: *
1008: * @param state a boolean value indicating whether the credentials
1009: * should be delegated or not.
1010: * @see #getCredDelegState()
1011: *
1012: * @throws GSSException containing the following
1013: * major error codes:
1014: * {@link GSSException#FAILURE GSSException.FAILURE}
1015: */
1016: public void requestCredDeleg(boolean state) throws GSSException;
1017:
1018: /**
1019: * Requests that the initiator's identity not be
1020: * disclosed to the acceptor. This request can only be made on the
1021: * context initiator's side and it has to be done prior to the first
1022: * call to <code>initSecContext</code>.
1023: *
1024: * Not all mechanisms support anonymity for the initiator. Therefore, the
1025: * application should check to see if the request was honored with the
1026: * {@link #getAnonymityState() getAnonymityState} method.<p>
1027: *
1028: * @param state a boolean value indicating if the initiator should
1029: * be authenticated to the acceptor as an anonymous principal.
1030: * @see #getAnonymityState
1031: *
1032: * @throws GSSException containing the following
1033: * major error codes:
1034: * {@link GSSException#FAILURE GSSException.FAILURE}
1035: */
1036: public void requestAnonymity(boolean state) throws GSSException;
1037:
1038: /**
1039: * Requests that data confidentiality be enabled
1040: * for the <code>wrap</code> method. This request can only be made on
1041: * the context initiator's side and it has to be done prior to the
1042: * first call to <code>initSecContext</code>.
1043: *
1044: * Not all mechanisms support confidentiality and other mechanisms
1045: * might enable it even if the application doesn't request
1046: * it. The application may check to see if the request was honored with
1047: * the {@link #getConfState() getConfState} method. If confidentiality
1048: * is enabled, only then will the mechanism honor a request for privacy
1049: * in the {@link MessageProp#MessageProp(int, boolean) MessageProp}
1050: * object that is passed in to the <code>wrap</code> method.<p>
1051: *
1052: * Enabling confidentiality will also automatically enable
1053: * integrity.<p>
1054: *
1055: * @param state a boolean value indicating whether confidentiality
1056: * should be enabled or not.
1057: * @see #getConfState()
1058: * @see #getIntegState()
1059: * @see #requestInteg(boolean)
1060: * @see MessageProp
1061: *
1062: * @throws GSSException containing the following
1063: * major error codes:
1064: * {@link GSSException#FAILURE GSSException.FAILURE}
1065: */
1066: public void requestConf(boolean state) throws GSSException;
1067:
1068: /**
1069: * Requests that data integrity be enabled
1070: * for the <code>wrap</code> and <code>getMIC</code>methods. This
1071: * request can only be made on the context initiator's side and it has
1072: * to be done prior to the first call to <code>initSecContext</code>.
1073: *
1074: * Not all mechanisms support integrity and other mechanisms
1075: * might enable it even if the application doesn't request
1076: * it. The application may check to see if the request was honored with
1077: * the {@link #getIntegState() getIntegState} method.<p>
1078: *
1079: * Disabling integrity will also automatically disable
1080: * confidentiality.<p>
1081: *
1082: * @param state a boolean value indicating whether integrity
1083: * should be enabled or not.
1084: * @see #getIntegState()
1085: *
1086: * @throws GSSException containing the following
1087: * major error codes:
1088: * {@link GSSException#FAILURE GSSException.FAILURE}
1089: */
1090: public void requestInteg(boolean state) throws GSSException;
1091:
1092: /**
1093: * Requests a lifetime in seconds for the
1094: * context. This method can only be called on the context initiator's
1095: * side and it has to be done prior to the first call to
1096: * <code>initSecContext</code>.<p>
1097: *
1098: * The actual lifetime of the context will depend on the capabilites of
1099: * the underlying mechanism and the application should call the {@link
1100: * #getLifetime() getLifetime} method to determine this.<p>
1101: *
1102: * @param lifetime the desired context lifetime in seconds. Use
1103: * <code>INDEFINITE_LIFETIME</code> to request an indefinite lifetime
1104: * and <code>DEFAULT_LIFETIME</code> to request a default lifetime.
1105: * @see #getLifetime()
1106: *
1107: * @throws GSSException containing the following
1108: * major error codes:
1109: * {@link GSSException#FAILURE GSSException.FAILURE}
1110: */
1111: public void requestLifetime(int lifetime) throws GSSException;
1112:
1113: /**
1114: * Sets the channel bindings to be used during context
1115: * establishment. This method can be called on both
1116: * the context initiator's and the context acceptor's side, but it must
1117: * be called before context establishment begins. This means that an
1118: * initiator must call it before the first call to
1119: * <code>initSecContext</code> and the acceptor must call it before the
1120: * first call to <code>acceptSecContext</code>.
1121: *
1122: * @param cb the channel bindings to use.
1123: *
1124: * @throws GSSException containing the following
1125: * major error codes:
1126: * {@link GSSException#FAILURE GSSException.FAILURE}
1127: */
1128: public void setChannelBinding(ChannelBinding cb)
1129: throws GSSException;
1130:
1131: /**
1132: * Determines if credential delegation is enabled on
1133: * this context. It can be called by both the context initiator and the
1134: * context acceptor. For a definitive answer this method must be
1135: * called only after context establishment is complete. Note that if an
1136: * initiator requests that delegation not be allowed the {@link
1137: * #requestCredDeleg(boolean) requestCredDeleg} method will honor that
1138: * request and this method will return <code>false</code> on the
1139: * initiator's side from that point onwards. <p>
1140: *
1141: * @return true if delegation is enabled, false otherwise.
1142: * @see #requestCredDeleg(boolean)
1143: */
1144: public boolean getCredDelegState();
1145:
1146: /**
1147: * Determines if mutual authentication is enabled on
1148: * this context. It can be called by both the context initiator and the
1149: * context acceptor. For a definitive answer this method must be
1150: * called only after context establishment is complete. An initiator
1151: * that requests mutual authentication can call this method after
1152: * context completion and dispose the context if its request was not
1153: * honored.<p>
1154: *
1155: * @return true if mutual authentication is enabled, false otherwise.
1156: * @see #requestMutualAuth(boolean)
1157: */
1158: public boolean getMutualAuthState();
1159:
1160: /**
1161: * Determines if replay detection is enabled for the
1162: * per-message security services from this context. It can be called by
1163: * both the context initiator and the context acceptor. For a
1164: * definitive answer this method must be called only after context
1165: * establishment is complete. An initiator that requests replay
1166: * detection can call this method after context completion and
1167: * dispose the context if its request was not honored.<p>
1168: *
1169: * @return true if replay detection is enabled, false otherwise.
1170: * @see #requestReplayDet(boolean)
1171: */
1172: public boolean getReplayDetState();
1173:
1174: /**
1175: * Determines if sequence checking is enabled for the
1176: * per-message security services from this context. It can be called by
1177: * both the context initiator and the context acceptor. For a
1178: * definitive answer this method must be called only after context
1179: * establishment is complete. An initiator that requests sequence
1180: * checking can call this method after context completion and
1181: * dispose the context if its request was not honored.<p>
1182: *
1183: * @return true if sequence checking is enabled, false otherwise.
1184: * @see #requestSequenceDet(boolean)
1185: */
1186: public boolean getSequenceDetState();
1187:
1188: /**
1189: * Determines if the context initiator is
1190: * anonymously authenticated to the context acceptor. It can be called by
1191: * both the context initiator and the context acceptor, and at any
1192: * time. <strong>On the initiator side, a call to this method determines
1193: * if the identity of the initiator has been disclosed in any of the
1194: * context establishment tokens that might have been generated thus far
1195: * by <code>initSecContext</code>. An initiator that absolutely must be
1196: * authenticated anonymously should call this method after each call to
1197: * <code>initSecContext</code> to determine if the generated token
1198: * should be sent to the peer or the context aborted.</strong> On the
1199: * acceptor side, a call to this method determines if any of the tokens
1200: * processed by <code>acceptSecContext</code> thus far have divulged
1201: * the identity of the initiator.<p>
1202: *
1203: * @return true if the context initiator is still anonymous, false
1204: * otherwise.
1205: * @see #requestAnonymity(boolean)
1206: */
1207: public boolean getAnonymityState();
1208:
1209: /**
1210: * Determines if the context is transferable to other processes
1211: * through the use of the {@link #export() export} method. This call
1212: * is only valid on fully established contexts.
1213: *
1214: * @return true if this context can be exported, false otherwise.
1215: *
1216: * @throws GSSException containing the following
1217: * major error codes:
1218: * {@link GSSException#FAILURE GSSException.FAILURE}
1219: */
1220: public boolean isTransferable() throws GSSException;
1221:
1222: /**
1223: * Determines if the context is ready for per message operations to be
1224: * used over it. Some mechanisms may allow the usage of the
1225: * per-message operations before the context is fully established.
1226: *
1227: * @return true if methods like <code>wrap</code>, <code>unwrap</code>,
1228: * <code>getMIC</code>, and <code>verifyMIC</code> can be used with
1229: * this context at the current stage of context establishment, false
1230: * otherwise.
1231: */
1232: public boolean isProtReady();
1233:
1234: /**
1235: * Determines if data confidentiality is available
1236: * over the context. This method can be called by both the context
1237: * initiator and the context acceptor, but only after one of {@link
1238: * #isProtReady() isProtReady} or {@link #isEstablished()
1239: * isEstablished} return <code>true</code>. If this method returns
1240: * <code>true</code>, so will {@link #getIntegState()
1241: * getIntegState}<p>
1242: *
1243: * @return true if confidentiality services are available, false
1244: * otherwise.
1245: * @see #requestConf(boolean)
1246: */
1247: public boolean getConfState();
1248:
1249: /**
1250: * Determines if data integrity is available
1251: * over the context. This method can be called by both the context
1252: * initiator and the context acceptor, but only after one of {@link
1253: * #isProtReady() isProtReady} or {@link #isEstablished()
1254: * isEstablished} return <code>true</code>. This method will always
1255: * return <code>true</code> if {@link #getConfState() getConfState}
1256: * returns true.<p>
1257: *
1258: * @return true if integrity services are available, false otherwise.
1259: * @see #requestInteg(boolean)
1260: */
1261: public boolean getIntegState();
1262:
1263: /**
1264: * Determines what the remaining lifetime for this
1265: * context is. It can be called by both the context initiator and the
1266: * context acceptor, but for a definitive answer it should be called
1267: * only after {@link #isEstablished() isEstablished} returns
1268: * true.<p>
1269: *
1270: * @return the remaining lifetime in seconds
1271: * @see #requestLifetime(int)
1272: */
1273: public int getLifetime();
1274:
1275: /**
1276: * Returns the name of the context initiator. This call is valid only
1277: * after one of {@link #isProtReady() isProtReady} or {@link
1278: * #isEstablished() isEstablished} return <code>true</code>.
1279: *
1280: * @return a GSSName that is an MN containing the name of the context
1281: * initiator.
1282: * @see GSSName
1283: *
1284: * @throws GSSException containing the following
1285: * major error codes:
1286: * {@link GSSException#FAILURE GSSException.FAILURE}
1287: */
1288: public GSSName getSrcName() throws GSSException;
1289:
1290: /**
1291: * Returns the name of the context acceptor. This call is valid only
1292: * after one of {@link #isProtReady() isProtReady} or {@link
1293: * #isEstablished() isEstablished} return <code>true</code>.
1294: *
1295: * @return a GSSName that is an MN containing the name of the context
1296: * acceptor.
1297: *
1298: * @throws GSSException containing the following
1299: * major error codes:
1300: * {@link GSSException#FAILURE GSSException.FAILURE}
1301: */
1302: public GSSName getTargName() throws GSSException;
1303:
1304: /**
1305: * Determines what mechanism is being used for this
1306: * context. This method may be called before the context is fully
1307: * established, but the mechanism returned may change on successive
1308: * calls in the negotiated mechanism case.
1309: *
1310: * @return the Oid of the mechanism being used
1311: *
1312: * @throws GSSException containing the following
1313: * major error codes:
1314: * {@link GSSException#FAILURE GSSException.FAILURE}
1315: */
1316: public Oid getMech() throws GSSException;
1317:
1318: /**
1319: * Obtains the credentials delegated by the context
1320: * initiator to the context acceptor. It should be called only on the
1321: * context acceptor's side, and once the context is fully
1322: * established. The caller can use the method {@link
1323: * #getCredDelegState() getCredDelegState} to determine if there are
1324: * any delegated credentials.
1325: *
1326: * @return a GSSCredential containing the initiator's delegated
1327: * credentials, or <code>null</code> is no credentials
1328: * were delegated.
1329: *
1330: * @throws GSSException containing the following
1331: * major error codes:
1332: * {@link GSSException#FAILURE GSSException.FAILURE}
1333: */
1334: public GSSCredential getDelegCred() throws GSSException;
1335:
1336: /**
1337: * Determines if this is the context initiator. This
1338: * can be called on both the context initiator's and context acceptor's
1339: * side.
1340: *
1341: * @return true if this is the context initiator, false if it is the
1342: * context acceptor.
1343: *
1344: * @throws GSSException containing the following
1345: * major error codes:
1346: * {@link GSSException#FAILURE GSSException.FAILURE}
1347: */
1348: public boolean isInitiator() throws GSSException;
1349: }
|