Source Code Cross Referenced for GSSContext.java in  » 6.0-JDK-Modules-sun » ietf » org » ietf » jgss » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » 6.0 JDK Modules sun » ietf » org.ietf.jgss 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


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:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.