Java > Open Source Codes > org > ietf > jgss > GSSContext


1 /*
2  * @(#)GSSContext.java 1.9 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package org.ietf.jgss;
9
10 import sun.security.jgss.spi.*;
11 import java.io.InputStream ;
12 import java.io.OutputStream ;
13
14 /**
15  * This interface encapsulates the GSS-API security context and provides
16  * the security services that are available over the context. Security
17  * contexts are established between peers using locally acquired
18  * credentials. Multiple contexts may exist simultaneously between a pair
19  * of peers, using the same or different set of credentials. GSS-API
20  * functions in a manner independent of the underlying transport protocol
21  * and depends on its calling application to transport the tokens that are
22  * generated by the security context between the peers.<p>
23  *
24  * If the caller instantiates the context using the default
25  * <code>GSSManager</code> instance, then the Kerberos v5 GSS-API mechanism
26  * is guaranteed to be available for context establishment. This mechanism
27  * is identified by the Oid "1.2.840.113554.1.2.2" and is defined in RFC
28  * 1964.<p>
29  *
30  * Before the context establishment phase is initiated, the context
31  * initiator may request specific characteristics desired of the
32  * established context. Not all underlying mechanisms support all
33  * characteristics that a caller might desire. After the context is
34  * established, the caller can check the actual characteristics and services
35  * offered by that context by means of various query methods. When using
36  * the Kerberos v5 GSS-API mechanism offered by the default
37  * <code>GSSManager</code> instance, all optional services will be
38  * available locally. They are mutual authentication, credential
39  * delegation, confidentiality and integrity protection, and per-message
40  * replay detection and sequencing. Note that in the GSS-API, message integrity
41  * is a prerequisite for message confidentiality.<p>
42  *
43  * The context establishment occurs in a loop where the
44  * initiator calls {@link #initSecContext(byte[], int, int) initSecContext}
45  * and the acceptor calls {@link #acceptSecContext(byte[], int, int)
46  * acceptSecContext} until the context is established. While in this loop
47  * the <code>initSecContext</code> and <code>acceptSecContext</code>
48  * methods produce tokens that the application sends over to the peer. The
49  * peer passes any such token as input to its <code>acceptSecContext</code>
50  * or <code>initSecContext</code> as the case may be.<p>
51  *
52  * During the context establishment phase, the {@link
53  * #isProtReady() isProtReady} method may be called to determine if the
54  * context can be used for the per-message operations of {@link
55  * #wrap(byte[], int, int, MessageProp) wrap} and {@link #getMIC(byte[],
56  * int, int, MessageProp) getMIC}. This allows applications to use
57  * per-message operations on contexts which aren't yet fully
58  * established.<p>
59  *
60  * After the context has been established or the <code>isProtReady</code>
61  * method returns <code>true</code>, the query routines can be invoked to
62  * determine the actual characteristics and services of the established
63  * context. The application can also start using the per-message methods
64  * of {@link #wrap(byte[], int, int, MessageProp) wrap} and
65  * {@link #getMIC(byte[], int, int, MessageProp) getMIC} to obtain
66  * cryptographic operations on application supplied data.<p>
67  *
68  * When the context is no longer needed, the application should call
69  * {@link #dispose() dispose} to release any system resources the context
70  * may be using.<p>
71  *
72  * A security context typically maintains sequencing and replay detection
73  * information about the tokens it processes. Therefore, the sequence in
74  * which any tokens are presented to this context for processing can be
75  * important. Also note that none of the methods in this interface are
76  * synchronized. Therefore, it is not advisable to share a
77  * <code>GSSContext</code> among several threads unless some application
78  * level synchronization is in place.<p>
79  *
80  * Finally, different mechanism providers might place different security
81  * restrictions on using GSS-API contexts. These will be documented by the
82  * mechanism provider. The application will need to ensure that it has the
83  * appropriate permissions if such checks are made in the mechanism layer.<p>
84  *
85  * The example code presented below demonstrates the usage of the
86  * <code>GSSContext</code> interface for the initiating peer. Different
87  * operations on the <code>GSSContext</code> object are presented,
88  * including: object instantiation, setting of desired flags, context
89  * establishment, query of actual context flags, per-message operations on
90  * application data, and finally context deletion.<p>
91  *
92  * <pre>
93  * // Create a context using default credentials
94  * // and the implementation specific default mechanism
95  * GSSManager manager ...
96  * GSSName targetName ...
97  * GSSContext context = manager.createContext(targetName, null, null,
98  * GSSContext.INDEFINITE_LIFETIME);
99  *
100  * // set desired context options prior to context establishment
101  * context.requestConf(true);
102  * context.requestMutualAuth(true);
103  * context.requestReplayDet(true);
104  * context.requestSequenceDet(true);
105  *
106  * // establish a context between peers
107  *
108  * byte []inToken = new byte[0];
109  *
110  * // Loop while there still is a token to be processed
111  *
112  * while (!context.isEstablished()) {
113  *
114  * byte[] outToken
115  * = context.initSecContext(inToken, 0, inToken.length);
116  *
117  * // send the output token if generated
118  * if (outToken != null)
119  * sendToken(outToken);
120  *
121  * if (!context.isEstablished()) {
122  * inToken = readToken();
123  * }
124  *
125  * // display context information
126  * System.out.println("Remaining lifetime in seconds = "
127  * + context.getLifetime());
128  * System.out.println("Context mechanism = " + context.getMech());
129  * System.out.println("Initiator = " + context.getSrcName());
130  * System.out.println("Acceptor = " + context.getTargName());
131  *
132  * if (context.getConfState())
133  * System.out.println("Confidentiality (i.e., privacy) is available");
134  *
135  * if (context.getIntegState())
136  * System.out.println("Integrity is available");
137  *
138  * // perform wrap on an application supplied message, appMsg,
139  * // using QOP = 0, and requesting privacy service
140  * byte [] appMsg ...
141  *
142  * MessageProp mProp = new MessageProp(0, true);
143  *
144  * byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp);
145  *
146  * sendToken(tok);
147  *
148  * // release the local-end of the context
149  * context.dispose();
150  *
151  * </pre>
152  *
153  * @author Mayank Upadhyay
154  * @version 1.9, 12/19/03
155  * @since 1.4
156  */
157 public interface GSSContext {
158
159     /**
160      * A lifetime constant representing the default context lifetime. This
161      * value is set to 0.
162      */
163     public static final int DEFAULT_LIFETIME = 0;
164     
165     /**
166      * A lifetime constant representing indefinite context lifetime.
167      * This value must is set to the maximum integer value in Java -
168      * {@link java.lang.Integer#MAX_VALUE Integer.MAX_VALUE}.
169      */
170     public static final int INDEFINITE_LIFETIME = Integer.MAX_VALUE;
171     
172     /**
173      * Called by the context initiator to start the context creation
174      * phase and process any tokens generated
175      * by the peer's <code>acceptSecContext</code> method.
176      * This method may return an output token which the application will need
177      * to send to the peer for processing by its <code>acceptSecContext</code>
178      * method. The application can call {@link #isEstablished()
179      * isEstablished} to determine if the context establishment phase is
180      * complete on this side of the context. A return value of
181      * <code>false</code> from <code>isEstablished</code> indicates that
182      * more tokens are expected to be supplied to
183      * <code>initSecContext</code>. Upon completion of the context
184      * establishment, the available context options may be queried through
185      * the get methods.<p>
186      *
187      * Note that it is possible that the <code>initSecContext</code> method
188      * return a token for the peer, and <code>isEstablished</code> return
189      * <code>true</code> also. This indicates that the token needs to be sent
190      * to the peer, but the local end of the context is now fully
191      * established.<p>
192      *
193      * Some mechanism providers might require that the caller be granted
194      * permission to initiate a security context. A failed permission check
195      * might cause a {@link java.lang.SecurityException SecurityException}
196      * to be thrown from this method.<p>
197      *
198      * @return a byte[] containing the token to be sent to the
199      * peer. <code>null</code> indicates that no token is generated.
200      * @param inputBuf token generated by the peer. This parameter is ignored
201      * on the first call since no token has been received from the peer.
202      * @param offset the offset within the inputBuf where the token begins.
203      * @param len the length of the token.
204      *
205      * @throws GSSException containing the following
206      * major error codes:
207      * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
208      * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
209      * {@link GSSException#NO_CRED GSSException.NO_CRED},
210      * {@link GSSException#CREDENTIALS_EXPIRED
211      * GSSException.CREDENTIALS_EXPIRED},
212      * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
213      * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
214      * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
215      * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
216      * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
217      * {@link GSSException#FAILURE GSSException.FAILURE}
218      */
219     public byte[] initSecContext(byte inputBuf[], int offset, int len)
220     throws GSSException ;
221     
222     /**
223      * Called by the context initiator to start the context creation
224      * phase and process any tokens generated
225      * by the peer's <code>acceptSecContext</code> method using
226      * streams. This method may write an output token to the
227      * <code>OutpuStream</code>, which the application will
228      * need to send to the peer for processing by its
229      * <code>acceptSecContext</code> call. Typically, the application would
230      * ensure this by calling the {@link java.io.OutputStream#flush() flush}
231      * method on an <code>OutputStream</code> that encapsulates the
232      * connection between the two peers. The application can
233      * determine if a token is written to the OutputStream from the return
234      * value of this method. A return value of <code>0</code> indicates that
235      * no token was written. The application can call
236      * {@link #isEstablished() isEstablished} to determine if the context
237      * establishment phase is complete on this side of the context. A
238      * return value of <code>false</code> from <code>isEstablished</code>
239      * indicates that more tokens are expected to be supplied to
240      * <code>initSecContext</code>.
241      * Upon completion of the context establishment, the available context
242      * options may be queried through the get methods.<p>
243      *
244      * Note that it is possible that the <code>initSecContext</code> method
245      * return a token for the peer, and <code>isEstablished</code> return
246      * <code>true</code> also. This indicates that the token needs to be sent
247      * to the peer, but the local end of the context is now fully
248      * established.<p>
249      *
250      * The GSS-API authentication tokens contain a definitive start and
251      * end. This method will attempt to read one of these tokens per
252      * invocation, and may block on the stream if only part of the token is
253      * available. In all other respects this method is equivalent to the
254      * byte array based {@link #initSecContext(byte[], int, int)
255      * initSecContext}.<p>
256      *
257      * Some mechanism providers might require that the caller be granted
258      * permission to initiate a security context. A failed permission check
259      * might cause a {@link java.lang.SecurityException SecurityException}
260      * to be thrown from this method.<p>
261      *
262      * The following example code demonstrates how this method might be
263      * used:<p>
264      * <pre>
265      * InputStream is ...
266      * OutputStream os ...
267      * GSSContext context ...
268      *
269      * // Loop while there is still a token to be processed
270      *
271      * while (!context.isEstablished()) {
272      *
273      * context.initSecContext(is, os);
274      *
275      * // send output token if generated
276      * os.flush();
277      * }
278      * </pre>
279      *
280      *
281      * @return the number of bytes written to the OutputStream as part of the
282      * token to be sent to the peer. A value of 0 indicates that no token
283      * needs to be sent.
284      * @param inStream an InputStream that contains the token generated by
285      * the peer. This parameter is ignored on the first call since no token
286      * has been or will be received from the peer at that point.
287      * @param outStream an OutputStream where the output token will be
288      * written. During the final stage of context establishment, there may be
289      * no bytes written.
290      *
291      * @throws GSSException containing the following
292      * major error codes:
293      * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
294      * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
295      * {@link GSSException#NO_CRED GSSException.NO_CRED},
296      * {@link GSSException#CREDENTIALS_EXPIRED GSSException.CREDENTIALS_EXPIRED},
297      * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
298      * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
299      * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
300      * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
301      * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
302      * {@link GSSException#FAILURE GSSException.FAILURE}
303      */
304     public int initSecContext(InputStream inStream,
305                   OutputStream outStream) throws GSSException ;
306     
307     /**
308      * Called by the context acceptor upon receiving a token from the
309      * peer. This method may return an output token which the application
310      * will need to send to the peer for further processing by its
311      * <code>initSecContext</code> call.<p>
312      *
313      * The application can call {@link #isEstablished() isEstablished} to
314      * determine if the context establishment phase is complete for this
315      * peer. A return value of <code>false</code> from
316      * <code>isEstablished</code> indicates that more tokens are expected to
317      * be supplied to this method. Upon completion of the context
318      * establishment, the available context options may be queried through
319      * the get methods.<p>
320      *
321      * Note that it is possible that <code>acceptSecContext</code> return a
322      * token for the peer, and <code>isEstablished</code> return
323      * <code>true</code> also. This indicates that the token needs to be
324      * sent to the peer, but the local end of the context is now fully
325      * established.<p>
326      *
327      * Some mechanism providers might require that the caller be granted
328      * permission to accept a security context. A failed permission check
329      * might cause a {@link java.lang.SecurityException SecurityException}
330      * to be thrown from this method.<p>
331      *
332      * The following example code demonstrates how this method might be
333      * used:<p>
334      * <pre>
335      * byte[] inToken;
336      * byte[] outToken;
337      * GSSContext context ...
338      *
339      * // Loop while there is still a token to be processed
340      *
341      * while (!context.isEstablished()) {
342      * inToken = readToken();
343      * outToken = context.acceptSecContext(inToken, 0,
344      * inToken.length);
345      * // send output token if generated
346      * if (outToken != null)
347      * sendToken(outToken);
348      * }
349      * </pre>
350      *
351      *
352      * @return a byte[] containing the token to be sent to the
353      * peer. <code>null</code> indicates that no token is generated.
354      * @param inToken token generated by the peer.
355      * @param offset the offset within the inToken where the token begins.
356      * @param len the length of the token.
357      *
358      * @throws GSSException containing the following
359      * major error codes:
360      * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
361      * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
362      * {@link GSSException#NO_CRED GSSException.NO_CRED},
363      * {@link GSSException#CREDENTIALS_EXPIRED
364      * GSSException.CREDENTIALS_EXPIRED},
365      * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
366      * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
367      * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
368      * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
369      * {@link GSSException#FAILURE GSSException.FAILURE}
370      */
371     public byte[] acceptSecContext(byte inToken[], int offset, int len)
372     throws GSSException ;
373     
374     /**
375      * Called by the context acceptor to process a token from the peer using
376      * streams. It may write an output token to the
377      * <code>OutputStream</code>, which the application
378      * will need to send to the peer for processing by its
379      * <code>initSecContext</code> method. Typically, the application would
380      * ensure this by calling the {@link java.io.OutputStream#flush() flush}
381      * method on an <code>OutputStream</code> that encapsulates the
382      * connection between the two peers. The application can call
383      * {@link #isEstablished() isEstablished} to determine if the context
384      * establishment phase is complete on this side of the context. A
385      * return value of <code>false</code> from <code>isEstablished</code>
386      * indicates that more tokens are expected to be supplied to
387      * <code>acceptSecContext</code>.
388      * Upon completion of the context establishment, the available context
389      * options may be queried through the get methods.<p>
390      *
391      * Note that it is possible that <code>acceptSecContext</code> return a
392      * token for the peer, and <code>isEstablished</code> return
393      * <code>true</code> also. This indicates that the token needs to be
394      * sent to the peer, but the local end of the context is now fully
395      * established.<p>
396      *
397      * The GSS-API authentication tokens contain a definitive start and
398      * end. This method will attempt to read one of these tokens per
399      * invocation, and may block on the stream if only part of the token is
400      * available. In all other respects this method is equivalent to the byte
401      * array based {@link #acceptSecContext(byte[], int, int)
402      * acceptSecContext}.<p>
403      *
404      * Some mechanism providers might require that the caller be granted
405      * permission to accept a security context. A failed permission check
406      * might cause a {@link java.lang.SecurityException SecurityException}
407      * to be thrown from this method.<p>
408      *
409      * The following example code demonstrates how this method might be
410      * used:<p>
411      * <pre>
412      * InputStream is ...
413      * OutputStream os ...
414      * GSSContext context ...
415      *
416      * // Loop while there is still a token to be processed
417      *
418      * while (!context.isEstablished()) {
419      *
420      * context.acceptSecContext(is, os);
421      *
422      * // send output token if generated
423      * os.flush();
424      * }
425      * </pre>
426      *
427      *
428      * @param inStream an InputStream that contains the token generated by
429      * the peer.
430      * @param outStream an OutputStream where the output token will be
431      * written. During the final stage of context establishment, there may be
432      * no bytes written.
433      *
434      * @throws GSSException containing the following
435      * major error codes:
436      * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
437      * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
438      * {@link GSSException#NO_CRED GSSException.NO_CRED},
439      * {@link GSSException#CREDENTIALS_EXPIRED
440      * GSSException.CREDENTIALS_EXPIRED},
441      * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
442      * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
443      * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
444      * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
445      * {@link GSSException#FAILURE GSSException.FAILURE}
446      */
447     /* Missing return value in RFC. int should have been returned.
448      * -----------------------------------------------------------
449      *
450      * The application can determine if a token is written to the
451      * OutputStream from the return value of this method. A return value of
452      * <code>0</code> indicates that no token was written.
453      *
454      * @return <strong>the number of bytes written to the
455      * OutputStream as part of the token to be sent to the peer. A value of
456      * 0 indicates that no token needs to be
457      * sent.</strong>
458      */
459     public void acceptSecContext(InputStream inStream,
460                  OutputStream outStream) throws GSSException ;
461     
462     /**
463      * Used during context establishment to determine the state of the
464      * context.
465      *
466      * @return <code>true</code> if this is a fully established context on
467      * the caller's side and no more tokens are needed from the peer.
468      */
469     public boolean isEstablished();
470   
471     /**
472      * Releases any system resources and cryptographic information stored in
473      * the context object and invalidates the context.
474      *
475      *
476      * @throws GSSException containing the following
477      * major error codes:
478      * {@link GSSException#FAILURE GSSException.FAILURE}
479      */
480     public void dispose() throws GSSException ;
481
482     /**
483      * Used to determine limits on the size of the message
484      * that can be passed to <code>wrap</code>. Returns the maximum
485      * message size that, if presented to the <code>wrap</code> method with
486      * the same <code>confReq</code> and <code>qop</code> parameters, will
487      * result in an output token containing no more
488      * than <code>maxTokenSize</code> bytes.<p>
489      *
490      * This call is intended for use by applications that communicate over
491      * protocols that impose a maximum message size. It enables the
492      * application to fragment messages prior to applying protection.<p>
493      *
494      * GSS-API implementations are recommended but not required to detect
495      * invalid QOP values when <code>getWrapSizeLimit</code> is called.
496      * This routine guarantees only a maximum message size, not the
497      * availability of specific QOP values for message protection.<p>
498      *
499      * @param qop the level of protection wrap will be asked to provide.
500      * @param confReq <code>true</code> if wrap will be asked to provide
501      * privacy, <code>false</code> otherwise.
502      * @param maxTokenSize the desired maximum size of the token emitted by
503      * wrap.
504      * @return the maximum size of the input token for the given output
505      * token size
506      *
507      * @throws GSSException containing the following
508      * major error codes:
509      * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
510      * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
511      * {@link GSSException#FAILURE GSSException.FAILURE}
512      */
513     public int getWrapSizeLimit(int qop, boolean confReq,
514                 int maxTokenSize) throws GSSException ;
515     
516     /**
517      * Applies per-message security services over the established security
518      * context. The method will return a token with the
519      * application supplied data and a cryptographic MIC over it.
520      * The data may be encrypted if confidentiality (privacy) was
521      * requested.<p>
522      *
523      * The MessageProp object is instantiated by the application and used
524      * to specify a QOP value which selects cryptographic algorithms, and a
525      * privacy service to optionally encrypt the message. The underlying
526      * mechanism that is used in the call may not be able to provide the
527      * privacy service. It sets the actual privacy service that it does
528      * provide in this MessageProp object which the caller should then
529      * query upon return. If the mechanism is not able to provide the
530      * requested QOP, it throws a GSSException with the BAD_QOP code.<p>
531      *
532      * Since some application-level protocols may wish to use tokens
533      * emitted by wrap to provide "secure framing", implementations should
534      * support the wrapping of zero-length messages.<p>
535      *
536      * The application will be responsible for sending the token to the
537      * peer.
538      *
539      * @param inBuf application data to be protected.
540      * @param offset the offset within the inBuf where the data begins.
541      * @param len the length of the data
542      * @param msgProp instance of MessageProp that is used by the
543      * application to set the desired QOP and privacy state. Set the
544      * desired QOP to 0 to request the default QOP. Upon return from this
545      * method, this object will contain the the actual privacy state that
546      * was applied to the message by the underlying mechanism.
547      * @return a byte[] containing the token to be sent to the peer.
548      *
549      * @throws GSSException containing the following major error codes:
550      * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
551      * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
552      * {@link GSSException#FAILURE GSSException.FAILURE}
553      */
554     public byte[] wrap(byte inBuf[], int offset, int len,
555                MessageProp msgProp) throws GSSException ;
556     
557     /**
558      * Applies per-message security services over the established security
559      * context using streams. The method will return a
560      * token with the application supplied data and a cryptographic MIC over it.
561      * The data may be encrypted if confidentiality
562      * (privacy) was requested. This method is equivalent to the byte array
563      * based {@link #wrap(byte[], int, int, MessageProp) wrap} method.<p>
564      *
565      * The application will be responsible for sending the token to the
566      * peer. Typically, the application would
567      * ensure this by calling the {@link java.io.OutputStream#flush() flush}
568      * method on an <code>OutputStream</code> that encapsulates the
569      * connection between the two peers.<p>
570      *
571      * The MessageProp object is instantiated by the application and used
572      * to specify a QOP value which selects cryptographic algorithms, and a
573      * privacy service to optionally encrypt the message. The underlying
574      * mechanism that is used in the call may not be able to provide the
575      * privacy service. It sets the actual privacy service that it does
576      * provide in this MessageProp object which the caller should then
577      * query upon return. If the mechanism is not able to provide the
578      * requested QOP, it throws a GSSException with the BAD_QOP code.<p>
579      *
580      * Since some application-level protocols may wish to use tokens
581      * emitted by wrap to provide "secure framing", implementations should
582      * support the wrapping of zero-length messages.<p>
583      *
584      * @param inStream an InputStream containing the application data to be
585      * protected. All of the data that is available in
586      * inStream is used.
587      * @param outStream an OutputStream to write the protected message
588      * to.
589      * @param msgProp instance of MessageProp that is used by the
590      * application to set the desired QOP and privacy state. Set the
591      * desired QOP to 0 to request the default QOP. Upon return from this
592      * method, this object will contain the the actual privacy state that
593      * was applied to the message by the underlying mechanism.
594      *
595      * @throws GSSException containing the following
596      * major error codes:
597      * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
598      * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
599      * {@link GSSException#FAILURE GSSException.FAILURE}
600      */
601     public void wrap(InputStream inStream, OutputStream outStream,
602              MessageProp msgProp) throws GSSException ;
603
604     /**
605      * Used to process tokens generated by the <code>wrap</code> method on
606      * the other side of the context. The method will return the message
607      * supplied by the peer application to its wrap call, while at the same
608      * time verifying the embedded MIC for that message.<p>
609      *
610      * The MessageProp object is instantiated by the application and is
611      * used by the underlying mechanism to return information to the caller
612      * such as the QOP, whether confidentiality was applied to the message,
613      * and other supplementary message state information.<p>
614      *
615      * Since some application-level protocols may wish to use tokens
616      * emitted by wrap to provide "secure framing", implementations should
617      * support the wrapping and unwrapping of zero-length messages.<p>
618      *
619      * @param inBuf a byte array containing the wrap token received from
620      * peer.
621      * @param offset the offset where the token begins.
622      * @param len the length of the token
623      * @param msgProp upon return from the method, this object will contain
624      * the applied QOP, the privacy state of the message, and supplementary
625      * information stating if the token was a duplicate, old, out of
626      * sequence or arriving after a gap.
627      * @return a byte[] containing the message unwrapped from the input
628      * token.
629      *
630      * @throws GSSException containing the following
631      * major error codes:
632      * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
633      * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
634      * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
635      * {@link GSSException#FAILURE GSSException.FAILURE}
636      */
637     public byte [] unwrap(byte[] inBuf, int offset, int len,
638               MessageProp msgProp) throws GSSException ;
639     
640     /**
641      * Uses streams to process tokens generated by the <code>wrap</code>
642      * method on the other side of the context. The method will return the
643      * message supplied by the peer application to its wrap call, while at
644      * the same time verifying the embedded MIC for that message.<p>
645      *
646      * The MessageProp object is instantiated by the application and is
647      * used by the underlying mechanism to return information to the caller
648      * such as the QOP, whether confidentiality was applied to the message,
649      * and other supplementary message state information.<p>
650      *
651      * Since some application-level protocols may wish to use tokens
652      * emitted by wrap to provide "secure framing", implementations should
653      * support the wrapping and unwrapping of zero-length messages.<p>
654      *
655      * The format of the input token that this method
656      * reads is defined in the specification for the underlying mechanism that
657      * will be used. This method will attempt to read one of these tokens per
658      * invocation. If the mechanism token contains a definitive start and
659      * end this method may block on the <code>InputStream</code> if only
660      * part of the token is available. If the start and end of the token
661      * are not definitive then the method will attempt to treat all
662      * available bytes as part of the token.<p>
663      *
664      * Other than the possible blocking behaviour described above, this
665      * method is equivalent to the byte array based {@link #unwrap(byte[],
666      * int, int, MessageProp) unwrap} method.<p>
667      *
668      * @param inStream an InputStream that contains the wrap token generated
669      * by the peer.
670      * @param outStream an OutputStream to write the application message
671      * to.
672      * @param msgProp upon return from the method, this object will contain
673      * the applied QOP, the privacy state of the message, and supplementary
674      * information stating if the token was a duplicate, old, out of
675      * sequence or arriving after a gap.
676      *
677      * @throws GSSException containing the following
678      * major error codes:
679      * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
680      * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
681      * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
682      * {@link GSSException#FAILURE GSSException.FAILURE}
683      */
684     public void unwrap(InputStream inStream, OutputStream outStream,
685                MessageProp msgProp) throws GSSException ;
686
687     /**
688      * Returns a token containing a cryptographic Message Integrity Code
689      * (MIC) for the supplied message, for transfer to the peer
690      * application. Unlike wrap, which encapsulates the user message in the
691      * returned token, only the message MIC is returned in the output
692      * token.<p>
693      *
694      * Note that privacy can only be applied through the wrap call.<p>
695      *
696      * Since some application-level protocols may wish to use tokens emitted
697      * by getMIC to provide "secure framing", implementations should support
698      * derivation of MICs from zero-length messages.
699      *
700      * @param inMsg the message to generate the MIC over.
701      * @param offset offset within the inMsg where the message begins.
702      * @param len the length of the message
703      * @param msgProp an instance of <code>MessageProp</code> that is used
704      * by the application to set the desired QOP. Set the desired QOP to
705      * <code>0</code> in <code>msgProp</code> to request the default
706      * QOP. Alternatively pass in <code>null</code> for <code>msgProp</code>
707      * to request the default QOP.
708      * @return a byte[] containing the token to be sent to the peer.
709      *
710      * @throws GSSException containing the following
711      * major error codes:
712      * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
713      * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
714      * {@link GSSException#FAILURE GSSException.FAILURE}
715      */
716     public byte[] getMIC(byte []inMsg, int offset, int len,
717              MessageProp msgProp) throws GSSException ;
718     
719     /**
720      * Uses streams to produce a token containing a cryptographic MIC for
721      * the supplied message, for transfer to the peer application.
722      * Unlike wrap, which encapsulates the user message in the returned
723      * token, only the message MIC is produced in the output token. This
724      * method is equivalent to the byte array based {@link #getMIC(byte[],
725      * int, int, MessageProp) getMIC} method.
726      *
727      * Note that privacy can only be applied through the wrap call.<p>
728      *
729      * Since some application-level protocols may wish to use tokens emitted
730      * by getMIC to provide "secure framing", implementations should support
731      * derivation of MICs from zero-length messages.
732      *
733      * @param inStream an InputStream containing the message to generate the
734      * MIC over. All of the data that is available in
735      * inStream is used.
736      * @param outStream an OutputStream to write the output token to.
737      * @param msgProp an instance of <code>MessageProp</code> that is used
738      * by the application to set the desired QOP. Set the desired QOP to
739      * <code>0</code> in <code>msgProp</code> to request the default
740      * QOP. Alternatively pass in <code>null</code> for <code>msgProp</code>
741      * to request the default QOP.
742      *
743      * @throws GSSException containing the following
744      * major error codes:
745      * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
746      * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
747      * {@link GSSException#FAILURE GSSException.FAILURE}
748      */
749     public void getMIC(InputStream inStream, OutputStream outStream,
750                MessageProp msgProp) throws GSSException ;
751     
752     /**
753      * Verifies the cryptographic MIC, contained in the token parameter,
754      * over the supplied message.<p>
755      *
756      * The MessageProp object is instantiated by the application and is used
757      * by the underlying mechanism to return information to the caller such
758      * as the QOP indicating the strength of protection that was applied to
759      * the message and other supplementary message state information.<p>
760      *
761      * Since some application-level protocols may wish to use tokens emitted
762      * by getMIC to provide "secure framing", implementations should support
763      * the calculation and verification of MICs over zero-length messages.
764      *
765      * @param inToken the token generated by peer's getMIC method.
766      * @param tokOffset the offset within the inToken where the token
767      * begins.
768      * @param tokLen the length of the token.
769      * @param inMsg the application message to verify the cryptographic MIC
770      * over.
771      * @param msgOffset the offset in inMsg where the message begins.
772      * @param msgLen the length of the message.
773      * @param msgProp upon return from the method, this object will contain
774      * the applied QOP and supplementary information stating if the token
775      * was a duplicate, old, out of sequence or arriving after a gap.
776      *
777      * @throws GSSException containing the following
778      * major error codes:
779      * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}
780      * {@link GSSException#BAD_MIC GSSException.BAD_MIC}
781      * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}
782      * {@link GSSException#FAILURE GSSException.FAILURE}
783      */
784     public void verifyMIC(byte[] inToken, int tokOffset, int tokLen,
785               byte[] inMsg, int msgOffset, int msgLen,
786               MessageProp msgProp) throws GSSException ;
787     
788     /**
789      * Uses streams to verify the cryptographic MIC, contained in the token
790      * parameter, over the supplied message. This method is equivalent to
791      * the byte array based {@link #verifyMIC(byte[], int, int, byte[], int,
792      * int, MessageProp) verifyMIC} method.
793      *
794      * The MessageProp object is instantiated by the application and is used
795      * by the underlying mechanism to return information to the caller such
796      * as the QOP indicating the strength of protection that was applied to
797      * the message and other supplementary message state information.<p>
798      *
799      * Since some application-level protocols may wish to use tokens emitted
800      * by getMIC to provide "secure framing", implementations should support
801      * the calculation and verification of MICs over zero-length messages.<p>
802      *
803      * The format of the input token that this method
804      * reads is defined in the specification for the underlying mechanism that
805      * will be used. This method will attempt to read one of these tokens per
806      * invocation. If the mechanism token contains a definitive start and
807      * end this method may block on the <code>InputStream</code> if only
808      * part of the token is available. If the start and end of the token
809      * are not definitive then the method will attempt to treat all
810      * available bytes as part of the token.<p>
811      *
812      * Other than the possible blocking behaviour described above, this
813      * method is equivalent to the byte array based {@link #verifyMIC(byte[],
814      * int, int, byte[], int, int, MessageProp) verifyMIC} method.<p>
815      *
816      * @param tokStream an InputStream containing the token generated by the
817      * peer's getMIC method.
818      * @param msgStream an InputStream containing the application message to
819      * verify the cryptographic MIC over. All of the data
820      * that is available in msgStream is used.
821      * @param msgProp upon return from the method, this object will contain
822      * the applied QOP and supplementary information stating if the token
823      * was a duplicate, old, out of sequence or arriving after a gap.
824      *
825      * @throws GSSException containing the following
826      * major error codes:
827      * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}
828      * {@link GSSException#BAD_MIC GSSException.BAD_MIC}
829      * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}
830      * {@link GSSException#FAILURE GSSException.FAILURE}
831      */
832     public void verifyMIC(InputStream tokStream, InputStream msgStream,
833               MessageProp msgProp) throws GSSException ;
834     
835     /**
836      * Exports this context so that another process may
837      * import it.. Provided to support the sharing of work between
838      * multiple processes. This routine will typically be used by the
839      * context-acceptor, in an application where a single process receives
840      * incoming connection requests and accepts security contexts over
841      * them, then passes the established context to one or more other
842      * processes for message exchange.<p>
843      *
844      * This method deactivates the security context and creates an
845      * interprocess token which, when passed to {@link
846      * GSSManager#createContext(byte[]) GSSManager.createContext} in
847      * another process, will re-activate the context in the second process.
848      * Only a single instantiation of a given context may be active at any
849      * one time; a subsequent attempt by a context exporter to access the
850      * exported security context will fail.<p>
851      *
852      * The implementation may constrain the set of processes by which the
853      * interprocess token may be imported, either as a function of local
854      * security policy, or as a result of implementation decisions. For
855      * example, some implementations may constrain contexts to be passed
856      * only between processes that run under the same account, or which are
857      * part of the same process group.<p>
858      *
859      * The interprocess token may contain security-sensitive information
860      * (for example cryptographic keys). While mechanisms are encouraged
861      * to either avoid placing such sensitive information within
862      * interprocess tokens, or to encrypt the token before returning it to
863      * the application, in a typical GSS-API implementation this may not be
864      * possible. Thus the application must take care to protect the
865      * interprocess token, and ensure that any process to which the token
866      * is transferred is trustworthy. <p>
867      *
868      * Implementations are not required to support the inter-process
869      * transfer of security contexts. Calling the {@link #isTransferable()
870      * isTransferable} method will indicate if the context object is
871      * transferable.<p>
872      *
873      * Calling this method on a context that
874      * is not exportable will result in this exception being thrown with
875      * the error code {@link GSSException#UNAVAILABLE
876      * GSSException.UNAVAILABLE}.
877      *
878      * @return a byte[] containing the exported context
879      * @see GSSManager#createContext(byte[])
880      *
881      * @throws GSSException containing the following
882      * major error codes:
883      * {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE},
884      * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
885      * {@link GSSException#NO_CONTEXT GSSException.NO_CONTEXT},
886      * {@link GSSException#FAILURE GSSException.FAILURE}
887      */
888     public byte [] export() throws GSSException ;
889     
890     /**
891      * Requests that mutual authentication be done during
892      * context establishment. This request can only be made on the context
893      * initiator's side and it has to be done prior to the first call to
894      * <code>initSecContext</code>.<p>
895      *
896      * Not all mechanisms support mutual authentication and some mechanisms
897      * might require mutual authentication even if the application
898      * doesn't. Therefore, the application should check to see if the
899      * request was honored with the {@link #getMutualAuthState()
900      * getMutualAuthState} method.<p>
901      *
902      * @param state a boolean value indicating whether mutual
903      * authentication shouls be used or not.
904      * @see #getMutualAuthState()
905      *
906      * @throws GSSException containing the following
907      * major error codes:
908      * {@link GSSException#FAILURE GSSException.FAILURE}
909      */
910     public void requestMutualAuth(boolean state) throws GSSException ;
911     
912     /**
913      * Requests that replay detection be enabled for the
914      * per-message security services after context establishemnt. This
915      * request can only be made on the context initiator's side and it has
916      * to be done prior to the first call to
917      * <code>initSecContext</code>. During context establishment replay
918      * detection is not an option and is a function of the underlying
919      * mechanism's capabilities.<p>
920      *
921      * Not all mechanisms support replay detection and some mechanisms
922      * might require replay detection even if the application
923      * doesn't. Therefore, the application should check to see if the
924      * request was honored with the {@link #getReplayDetState()
925      * getReplayDetState} method. If replay detection is enabled then the
926      * {@link MessageProp#isDuplicateToken() MessageProp.isDuplicateToken} and {@link
927      * MessageProp#isOldToken() MessageProp.isOldToken} methods will return
928      * valid results for the <code>MessageProp</code> object that is passed
929      * in to the <code>unwrap</code> method or the <code>verifyMIC</code>
930      * method.<p>
931      *
932      * @param state a boolean value indicating whether replay detection
933      * should be enabled over the established context or not.
934      * @see #getReplayDetState()
935      *
936      * @throws GSSException containing the following
937      * major error codes:
938      * {@link GSSException#FAILURE GSSException.FAILURE}
939      */
940     public void requestReplayDet(boolean state) throws GSSException ;
941     
942     /**
943      * Requests that sequence checking be enabled for the
944      * per-message security services after context establishemnt. This
945      * request can only be made on the context initiator's side and it has
946      * to be done prior to the first call to
947      * <code>initSecContext</code>. During context establishment sequence
948      * checking is not an option and is a function of the underlying
949      * mechanism's capabilities.<p>
950      *
951      * Not all mechanisms support sequence checking and some mechanisms
952      * might require sequence checking even if the application
953      * doesn't. Therefore, the application should check to see if the
954      * request was honored with the {@link #getSequenceDetState()
955      * getSequenceDetState} method. If sequence checking is enabled then the
956      * {@link MessageProp#isDuplicateToken() MessageProp.isDuplicateToken},
957      * {@link MessageProp#isOldToken() MessageProp.isOldToken},
958      * {@link MessageProp#isUnseqToken() MessageProp.isUnseqToken}, and
959      * {@link MessageProp#isGapToken() MessageProp.isGapToken} methods will return
960      * valid results for the <code>MessageProp</code> object that is passed
961      * in to the <code>unwrap</code> method or the <code>verifyMIC</code>
962      * method.<p>
963      *
964      * @param state a boolean value indicating whether sequence checking
965      * should be enabled over the established context or not.
966      * @see #getSequenceDetState()
967      *
968      * @throws GSSException containing the following
969      * major error codes:
970      * {@link GSSException#FAILURE GSSException.FAILURE}
971      */
972     public void requestSequenceDet(boolean state) throws GSSException ;
973     
974     /**
975      * Requests that the initiator's credentials be
976      * delegated to the acceptor during context establishment. This
977      * request can only be made on the context initiator's side and it has
978      * to be done prior to the first call to
979      * <code>initSecContext</code>.
980      *
981      * Not all mechanisms support credential delegation. Therefore, an
982      * application that desires delegation should check to see if the
983      * request was honored with the {@link #getCredDelegState()
984      * getCredDelegState} method. If the application indicates that
985      * delegation must not be used, then the mechanism will honor the
986      * request and delegation will not occur. This is an exception
987      * to the general rule that a mechanism may enable a service even if it
988      * is not requested.<p>
989      *
990      * @param state a bo