1 /*
2 * Copyright 2000-2001 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package org.ietf.jgss;
27
28 import sun.security.jgss.spi;
29 import java.io.InputStream;
30 import java.io.OutputStream;
31
32 /**
33 * This interface encapsulates the GSS-API security context and provides
34 * the security services that are available over the context. Security
35 * contexts are established between peers using locally acquired
36 * credentials. Multiple contexts may exist simultaneously between a pair
37 * of peers, using the same or different set of credentials. GSS-API
38 * functions in a manner independent of the underlying transport protocol
39 * and depends on its calling application to transport the tokens that are
40 * generated by the security context between the peers.<p>
41 *
42 * If the caller instantiates the context using the default
43 * <code>GSSManager</code> instance, then the Kerberos v5 GSS-API mechanism
44 * is guaranteed to be available for context establishment. This mechanism
45 * is identified by the Oid "1.2.840.113554.1.2.2" and is defined in RFC
46 * 1964.<p>
47 *
48 * Before the context establishment phase is initiated, the context
49 * initiator may request specific characteristics desired of the
50 * established context. Not all underlying mechanisms support all
51 * characteristics that a caller might desire. After the context is
52 * established, the caller can check the actual characteristics and services
53 * offered by that context by means of various query methods. When using
54 * the Kerberos v5 GSS-API mechanism offered by the default
55 * <code>GSSManager</code> instance, all optional services will be
56 * available locally. They are mutual authentication, credential
57 * delegation, confidentiality and integrity protection, and per-message
58 * replay detection and sequencing. Note that in the GSS-API, message integrity
59 * is a prerequisite for message confidentiality.<p>
60 *
61 * The context establishment occurs in a loop where the
62 * initiator calls {@link #initSecContext(byte[], int, int) initSecContext}
63 * and the acceptor calls {@link #acceptSecContext(byte[], int, int)
64 * acceptSecContext} until the context is established. While in this loop
65 * the <code>initSecContext</code> and <code>acceptSecContext</code>
66 * methods produce tokens that the application sends over to the peer. The
67 * peer passes any such token as input to its <code>acceptSecContext</code>
68 * or <code>initSecContext</code> as the case may be.<p>
69 *
70 * During the context establishment phase, the {@link
71 * #isProtReady() isProtReady} method may be called to determine if the
72 * context can be used for the per-message operations of {@link
73 * #wrap(byte[], int, int, MessageProp) wrap} and {@link #getMIC(byte[],
74 * int, int, MessageProp) getMIC}. This allows applications to use
75 * per-message operations on contexts which aren't yet fully
76 * established.<p>
77 *
78 * After the context has been established or the <code>isProtReady</code>
79 * method returns <code>true</code>, the query routines can be invoked to
80 * determine the actual characteristics and services of the established
81 * context. The application can also start using the per-message methods
82 * of {@link #wrap(byte[], int, int, MessageProp) wrap} and
83 * {@link #getMIC(byte[], int, int, MessageProp) getMIC} to obtain
84 * cryptographic operations on application supplied data.<p>
85 *
86 * When the context is no longer needed, the application should call
87 * {@link #dispose() dispose} to release any system resources the context
88 * may be using.<p>
89 *
90 * A security context typically maintains sequencing and replay detection
91 * information about the tokens it processes. Therefore, the sequence in
92 * which any tokens are presented to this context for processing can be
93 * important. Also note that none of the methods in this interface are
94 * synchronized. Therefore, it is not advisable to share a
95 * <code>GSSContext</code> among several threads unless some application
96 * level synchronization is in place.<p>
97 *
98 * Finally, different mechanism providers might place different security
99 * restrictions on using GSS-API contexts. These will be documented by the
100 * mechanism provider. The application will need to ensure that it has the
101 * appropriate permissions if such checks are made in the mechanism layer.<p>
102 *
103 * The example code presented below demonstrates the usage of the
104 * <code>GSSContext</code> interface for the initiating peer. Different
105 * operations on the <code>GSSContext</code> object are presented,
106 * including: object instantiation, setting of desired flags, context
107 * establishment, query of actual context flags, per-message operations on
108 * application data, and finally context deletion.<p>
109 *
110 * <pre>
111 * // Create a context using default credentials
112 * // and the implementation specific default mechanism
113 * GSSManager manager ...
114 * GSSName targetName ...
115 * GSSContext context = manager.createContext(targetName, null, null,
116 * GSSContext.INDEFINITE_LIFETIME);
117 *
118 * // set desired context options prior to context establishment
119 * context.requestConf(true);
120 * context.requestMutualAuth(true);
121 * context.requestReplayDet(true);
122 * context.requestSequenceDet(true);
123 *
124 * // establish a context between peers
125 *
126 * byte []inToken = new byte[0];
127 *
128 * // Loop while there still is a token to be processed
129 *
130 * while (!context.isEstablished()) {
131 *
132 * byte[] outToken
133 * = context.initSecContext(inToken, 0, inToken.length);
134 *
135 * // send the output token if generated
136 * if (outToken != null)
137 * sendToken(outToken);
138 *
139 * if (!context.isEstablished()) {
140 * inToken = readToken();
141 * }
142 *
143 * // display context information
144 * System.out.println("Remaining lifetime in seconds = "
145 * + context.getLifetime());
146 * System.out.println("Context mechanism = " + context.getMech());
147 * System.out.println("Initiator = " + context.getSrcName());
148 * System.out.println("Acceptor = " + context.getTargName());
149 *
150 * if (context.getConfState())
151 * System.out.println("Confidentiality (i.e., privacy) is available");
152 *
153 * if (context.getIntegState())
154 * System.out.println("Integrity is available");
155 *
156 * // perform wrap on an application supplied message, appMsg,
157 * // using QOP = 0, and requesting privacy service
158 * byte [] appMsg ...
159 *
160 * MessageProp mProp = new MessageProp(0, true);
161 *
162 * byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp);
163 *
164 * sendToken(tok);
165 *
166 * // release the local-end of the context
167 * context.dispose();
168 *
169 * </pre>
170 *
171 * @author Mayank Upadhyay
172 * @since 1.4
173 */
174 public interface GSSContext {
175
176 /**
177 * A lifetime constant representing the default context lifetime. This
178 * value is set to 0.
179 */
180 public static final int DEFAULT_LIFETIME = 0;
181
182 /**
183 * A lifetime constant representing indefinite context lifetime.
184 * This value must is set to the maximum integer value in Java -
185 * {@link java.lang.Integer#MAX_VALUE Integer.MAX_VALUE}.
186 */
187 public static final int INDEFINITE_LIFETIME = Integer.MAX_VALUE;
188
189 /**
190 * Called by the context initiator to start the context creation
191 * phase and process any tokens generated
192 * by the peer's <code>acceptSecContext</code> method.
193 * This method may return an output token which the application will need
194 * to send to the peer for processing by its <code>acceptSecContext</code>
195 * method. The application can call {@link #isEstablished()
196 * isEstablished} to determine if the context establishment phase is
197 * complete on this side of the context. A return value of
198 * <code>false</code> from <code>isEstablished</code> indicates that
199 * more tokens are expected to be supplied to
200 * <code>initSecContext</code>. Upon completion of the context
201 * establishment, the available context options may be queried through
202 * the get methods.<p>
203 *
204 * Note that it is possible that the <code>initSecContext</code> method
205 * return a token for the peer, and <code>isEstablished</code> return
206 * <code>true</code> also. This indicates that the token needs to be sent
207 * to the peer, but the local end of the context is now fully
208 * established.<p>
209 *
210 * Some mechanism providers might require that the caller be granted
211 * permission to initiate a security context. A failed permission check
212 * might cause a {@link java.lang.SecurityException SecurityException}
213 * to be thrown from this method.<p>
214 *
215 * @return a byte[] containing the token to be sent to the
216 * peer. <code>null</code> indicates that no token is generated.
217 * @param inputBuf token generated by the peer. This parameter is ignored
218 * on the first call since no token has been received from the peer.
219 * @param offset the offset within the inputBuf where the token begins.
220 * @param len the length of the token.
221 *
222 * @throws GSSException containing the following
223 * major error codes:
224 * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
225 * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
226 * {@link GSSException#NO_CRED GSSException.NO_CRED},
227 * {@link GSSException#CREDENTIALS_EXPIRED
228 * GSSException.CREDENTIALS_EXPIRED},
229 * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
230 * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
231 * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
232 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
233 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
234 * {@link GSSException#FAILURE GSSException.FAILURE}
235 */
236 public byte[] initSecContext(byte inputBuf[], int offset, int len)
237 throws GSSException;
238
239 /**
240 * Called by the context initiator to start the context creation
241 * phase and process any tokens generated
242 * by the peer's <code>acceptSecContext</code> method using
243 * streams. This method may write an output token to the
244 * <code>OutpuStream</code>, which the application will
245 * need to send to the peer for processing by its
246 * <code>acceptSecContext</code> call. Typically, the application would
247 * ensure this by calling the {@link java.io.OutputStream#flush() flush}
248 * method on an <code>OutputStream</code> that encapsulates the
249 * connection between the two peers. The application can
250 * determine if a token is written to the OutputStream from the return
251 * value of this method. A return value of <code>0</code> indicates that
252 * no token was written. The application can call
253 * {@link #isEstablished() isEstablished} to determine if the context
254 * establishment phase is complete on this side of the context. A
255 * return value of <code>false</code> from <code>isEstablished</code>
256 * indicates that more tokens are expected to be supplied to
257 * <code>initSecContext</code>.
258 * Upon completion of the context establishment, the available context
259 * options may be queried through the get methods.<p>
260 *
261 * Note that it is possible that the <code>initSecContext</code> method
262 * return a token for the peer, and <code>isEstablished</code> return
263 * <code>true</code> also. This indicates that the token needs to be sent
264 * to the peer, but the local end of the context is now fully
265 * established.<p>
266 *
267 * The GSS-API authentication tokens contain a definitive start and
268 * end. This method will attempt to read one of these tokens per
269 * invocation, and may block on the stream if only part of the token is
270 * available. In all other respects this method is equivalent to the
271 * byte array based {@link #initSecContext(byte[], int, int)
272 * initSecContext}.<p>
273 *
274 * Some mechanism providers might require that the caller be granted
275 * permission to initiate a security context. A failed permission check
276 * might cause a {@link java.lang.SecurityException SecurityException}
277 * to be thrown from this method.<p>
278 *
279 * The following example code demonstrates how this method might be
280 * used:<p>
281 * <pre>
282 * InputStream is ...
283 * OutputStream os ...
284 * GSSContext context ...
285 *
286 * // Loop while there is still a token to be processed
287 *
288 * while (!context.isEstablished()) {
289 *
290 * context.initSecContext(is, os);
291 *
292 * // send output token if generated
293 * os.flush();
294 * }
295 * </pre>
296 *
297 *
298 * @return the number of bytes written to the OutputStream as part of the
299 * token to be sent to the peer. A value of 0 indicates that no token
300 * needs to be sent.
301 * @param inStream an InputStream that contains the token generated by
302 * the peer. This parameter is ignored on the first call since no token
303 * has been or will be received from the peer at that point.
304 * @param outStream an OutputStream where the output token will be
305 * written. During the final stage of context establishment, there may be
306 * no bytes written.
307 *
308 * @throws GSSException containing the following
309 * major error codes:
310 * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
311 * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
312 * {@link GSSException#NO_CRED GSSException.NO_CRED},
313 * {@link GSSException#CREDENTIALS_EXPIRED GSSException.CREDENTIALS_EXPIRED},
314 * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
315 * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
316 * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
317 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
318 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
319 * {@link GSSException#FAILURE GSSException.FAILURE}
320 */
321 public int initSecContext(InputStream inStream,
322 OutputStream outStream) throws GSSException;
323
324 /**
325 * Called by the context acceptor upon receiving a token from the
326 * peer. This method may return an output token which the application
327 * will need to send to the peer for further processing by its
328 * <code>initSecContext</code> call.<p>
329 *
330 * The application can call {@link #isEstablished() isEstablished} to
331 * determine if the context establishment phase is complete for this
332 * peer. A return value of <code>false</code> from
333 * <code>isEstablished</code> indicates that more tokens are expected to
334 * be supplied to this method. Upon completion of the context
335 * establishment, the available context options may be queried through
336 * the get methods.<p>
337 *
338 * Note that it is possible that <code>acceptSecContext</code> return a
339 * token for the peer, and <code>isEstablished</code> return
340 * <code>true</code> also. This indicates that the token needs to be
341 * sent to the peer, but the local end of the context is now fully
342 * established.<p>
343 *
344 * Some mechanism providers might require that the caller be granted
345 * permission to accept a security context. A failed permission check
346 * might cause a {@link java.lang.SecurityException SecurityException}
347 * to be thrown from this method.<p>
348 *
349 * The following example code demonstrates how this method might be
350 * used:<p>
351 * <pre>
352 * byte[] inToken;
353 * byte[] outToken;
354 * GSSContext context ...
355 *
356 * // Loop while there is still a token to be processed
357 *
358 * while (!context.isEstablished()) {
359 * inToken = readToken();
360 * outToken = context.acceptSecContext(inToken, 0,
361 * inToken.length);
362 * // send output token if generated
363 * if (outToken != null)
364 * sendToken(outToken);
365 * }
366 * </pre>
367 *
368 *
369 * @return a byte[] containing the token to be sent to the
370 * peer. <code>null</code> indicates that no token is generated.
371 * @param inToken token generated by the peer.
372 * @param offset the offset within the inToken where the token begins.
373 * @param len the length of the token.
374 *
375 * @throws GSSException containing the following
376 * major error codes:
377 * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
378 * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
379 * {@link GSSException#NO_CRED GSSException.NO_CRED},
380 * {@link GSSException#CREDENTIALS_EXPIRED
381 * GSSException.CREDENTIALS_EXPIRED},
382 * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
383 * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
384 * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
385 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
386 * {@link GSSException#FAILURE GSSException.FAILURE}
387 */
388 public byte[] acceptSecContext(byte inToken[], int offset, int len)
389 throws GSSException;
390
391 /**
392 * Called by the context acceptor to process a token from the peer using
393 * streams. It may write an output token to the
394 * <code>OutputStream</code>, which the application
395 * will need to send to the peer for processing by its
396 * <code>initSecContext</code> method. Typically, the application would
397 * ensure this by calling the {@link java.io.OutputStream#flush() flush}
398 * method on an <code>OutputStream</code> that encapsulates the
399 * connection between the two peers. The application can call
400 * {@link #isEstablished() isEstablished} to determine if the context
401 * establishment phase is complete on this side of the context. A
402 * return value of <code>false</code> from <code>isEstablished</code>
403 * indicates that more tokens are expected to be supplied to
404 * <code>acceptSecContext</code>.
405 * Upon completion of the context establishment, the available context
406 * options may be queried through the get methods.<p>
407 *
408 * Note that it is possible that <code>acceptSecContext</code> return a
409 * token for the peer, and <code>isEstablished</code> return
410 * <code>true</code> also. This indicates that the token needs to be
411 * sent to the peer, but the local end of the context is now fully
412 * established.<p>
413 *
414 * The GSS-API authentication tokens contain a definitive start and
415 * end. This method will attempt to read one of these tokens per
416 * invocation, and may block on the stream if only part of the token is
417 * available. In all other respects this method is equivalent to the byte
418 * array based {@link #acceptSecContext(byte[], int, int)
419 * acceptSecContext}.<p>
420 *
421 * Some mechanism providers might require that the caller be granted
422 * permission to accept a security context. A failed permission check
423 * might cause a {@link java.lang.SecurityException SecurityException}
424 * to be thrown from this method.<p>
425 *
426 * The following example code demonstrates how this method might be
427 * used:<p>
428 * <pre>
429 * InputStream is ...
430 * OutputStream os ...
431 * GSSContext context ...
432 *
433 * // Loop while there is still a token to be processed
434 *
435 * while (!context.isEstablished()) {
436 *
437 * context.acceptSecContext(is, os);
438 *
439 * // send output token if generated
440 * os.flush();
441 * }
442 * </pre>
443 *
444 *
445 * @param inStream an InputStream that contains the token generated by
446 * the peer.
447 * @param outStream an OutputStream where the output token will be
448 * written. During the final stage of context establishment, there may be
449 * no bytes written.
450 *
451 * @throws GSSException containing the following
452 * major error codes:
453 * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
454 * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
455 * {@link GSSException#NO_CRED GSSException.NO_CRED},
456 * {@link GSSException#CREDENTIALS_EXPIRED
457 * GSSException.CREDENTIALS_EXPIRED},
458 * {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS},
459 * {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN},
460 * {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN},
461 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
462 * {@link GSSException#FAILURE GSSException.FAILURE}
463 */
464 /* Missing return value in RFC. int should have been returned.
465 * -----------------------------------------------------------
466 *
467 * The application can determine if a token is written to the
468 * OutputStream from the return value of this method. A return value of
469 * <code>0</code> indicates that no token was written.
470 *
471 * @return <strong>the number of bytes written to the
472 * OutputStream as part of the token to be sent to the peer. A value of
473 * 0 indicates that no token needs to be
474 * sent.</strong>
475 */
476 public void acceptSecContext(InputStream inStream,
477 OutputStream outStream) throws GSSException;
478
479 /**
480 * Used during context establishment to determine the state of the
481 * context.
482 *
483 * @return <code>true</code> if this is a fully established context on
484 * the caller's side and no more tokens are needed from the peer.
485 */
486 public boolean isEstablished();
487
488 /**
489 * Releases any system resources and cryptographic information stored in
490 * the context object and invalidates the context.
491 *
492 *
493 * @throws GSSException containing the following
494 * major error codes:
495 * {@link GSSException#FAILURE GSSException.FAILURE}
496 */
497 public void dispose() throws GSSException;
498
499 /**
500 * Used to determine limits on the size of the message
501 * that can be passed to <code>wrap</code>. Returns the maximum
502 * message size that, if presented to the <code>wrap</code> method with
503 * the same <code>confReq</code> and <code>qop</code> parameters, will
504 * result in an output token containing no more
505 * than <code>maxTokenSize</code> bytes.<p>
506 *
507 * This call is intended for use by applications that communicate over
508 * protocols that impose a maximum message size. It enables the
509 * application to fragment messages prior to applying protection.<p>
510 *
511 * GSS-API implementations are recommended but not required to detect
512 * invalid QOP values when <code>getWrapSizeLimit</code> is called.
513 * This routine guarantees only a maximum message size, not the
514 * availability of specific QOP values for message protection.<p>
515 *
516 * @param qop the level of protection wrap will be asked to provide.
517 * @param confReq <code>true</code> if wrap will be asked to provide
518 * privacy, <code>false</code> otherwise.
519 * @param maxTokenSize the desired maximum size of the token emitted by
520 * wrap.
521 * @return the maximum size of the input token for the given output
522 * token size
523 *
524 * @throws GSSException containing the following
525 * major error codes:
526 * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
527 * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
528 * {@link GSSException#FAILURE GSSException.FAILURE}
529 */
530 public int getWrapSizeLimit(int qop, boolean confReq,
531 int maxTokenSize) throws GSSException;
532
533 /**
534 * Applies per-message security services over the established security
535 * context. The method will return a token with the
536 * application supplied data and a cryptographic MIC over it.
537 * The data may be encrypted if confidentiality (privacy) was
538 * requested.<p>
539 *
540 * The MessageProp object is instantiated by the application and used
541 * to specify a QOP value which selects cryptographic algorithms, and a
542 * privacy service to optionally encrypt the message. The underlying
543 * mechanism that is used in the call may not be able to provide the
544 * privacy service. It sets the actual privacy service that it does
545 * provide in this MessageProp object which the caller should then
546 * query upon return. If the mechanism is not able to provide the
547 * requested QOP, it throws a GSSException with the BAD_QOP code.<p>
548 *
549 * Since some application-level protocols may wish to use tokens
550 * emitted by wrap to provide "secure framing", implementations should
551 * support the wrapping of zero-length messages.<p>
552 *
553 * The application will be responsible for sending the token to the
554 * peer.
555 *
556 * @param inBuf application data to be protected.
557 * @param offset the offset within the inBuf where the data begins.
558 * @param len the length of the data
559 * @param msgProp instance of MessageProp that is used by the
560 * application to set the desired QOP and privacy state. Set the
561 * desired QOP to 0 to request the default QOP. Upon return from this
562 * method, this object will contain the the actual privacy state that
563 * was applied to the message by the underlying mechanism.
564 * @return a byte[] containing the token to be sent to the peer.
565 *
566 * @throws GSSException containing the following major error codes:
567 * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
568 * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
569 * {@link GSSException#FAILURE GSSException.FAILURE}
570 */
571 public byte[] wrap(byte inBuf[], int offset, int len,
572 MessageProp msgProp) throws GSSException;
573
574 /**
575 * Applies per-message security services over the established security
576 * context using streams. The method will return a
577 * token with the application supplied data and a cryptographic MIC over it.
578 * The data may be encrypted if confidentiality
579 * (privacy) was requested. This method is equivalent to the byte array
580 * based {@link #wrap(byte[], int, int, MessageProp) wrap} method.<p>
581 *
582 * The application will be responsible for sending the token to the
583 * peer. Typically, the application would
584 * ensure this by calling the {@link java.io.OutputStream#flush() flush}
585 * method on an <code>OutputStream</code> that encapsulates the
586 * connection between the two peers.<p>
587 *
588 * The MessageProp object is instantiated by the application and used
589 * to specify a QOP value which selects cryptographic algorithms, and a
590 * privacy service to optionally encrypt the message. The underlying
591 * mechanism that is used in the call may not be able to provide the
592 * privacy service. It sets the actual privacy service that it does
593 * provide in this MessageProp object which the caller should then
594 * query upon return. If the mechanism is not able to provide the
595 * requested QOP, it throws a GSSException with the BAD_QOP code.<p>
596 *
597 * Since some application-level protocols may wish to use tokens
598 * emitted by wrap to provide "secure framing", implementations should
599 * support the wrapping of zero-length messages.<p>
600 *
601 * @param inStream an InputStream containing the application data to be
602 * protected. All of the data that is available in
603 * inStream is used.
604 * @param outStream an OutputStream to write the protected message
605 * to.
606 * @param msgProp instance of MessageProp that is used by the
607 * application to set the desired QOP and privacy state. Set the
608 * desired QOP to 0 to request the default QOP. Upon return from this
609 * method, this object will contain the the actual privacy state that
610 * was applied to the message by the underlying mechanism.
611 *
612 * @throws GSSException containing the following
613 * major error codes:
614 * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
615 * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
616 * {@link GSSException#FAILURE GSSException.FAILURE}
617 */
618 public void wrap(InputStream inStream, OutputStream outStream,
619 MessageProp msgProp) throws GSSException;
620
621 /**
622 * Used to process tokens generated by the <code>wrap</code> method on
623 * the other side of the context. The method will return the message
624 * supplied by the peer application to its wrap call, while at the same
625 * time verifying the embedded MIC for that message.<p>
626 *
627 * The MessageProp object is instantiated by the application and is
628 * used by the underlying mechanism to return information to the caller
629 * such as the QOP, whether confidentiality was applied to the message,
630 * and other supplementary message state information.<p>
631 *
632 * Since some application-level protocols may wish to use tokens
633 * emitted by wrap to provide "secure framing", implementations should
634 * support the wrapping and unwrapping of zero-length messages.<p>
635 *
636 * @param inBuf a byte array containing the wrap token received from
637 * peer.
638 * @param offset the offset where the token begins.
639 * @param len the length of the token
640 * @param msgProp upon return from the method, this object will contain
641 * the applied QOP, the privacy state of the message, and supplementary
642 * information stating if the token was a duplicate, old, out of
643 * sequence or arriving after a gap.
644 * @return a byte[] containing the message unwrapped from the input
645 * token.
646 *
647 * @throws GSSException containing the following
648 * major error codes:
649 * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
650 * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
651 * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
652 * {@link GSSException#FAILURE GSSException.FAILURE}
653 */
654 public byte [] unwrap(byte[] inBuf, int offset, int len,
655 MessageProp msgProp) throws GSSException;
656
657 /**
658 * Uses streams to process tokens generated by the <code>wrap</code>
659 * method on the other side of the context. The method will return the
660 * message supplied by the peer application to its wrap call, while at
661 * the same time verifying the embedded MIC for that message.<p>
662 *
663 * The MessageProp object is instantiated by the application and is
664 * used by the underlying mechanism to return information to the caller
665 * such as the QOP, whether confidentiality was applied to the message,
666 * and other supplementary message state information.<p>
667 *
668 * Since some application-level protocols may wish to use tokens
669 * emitted by wrap to provide "secure framing", implementations should
670 * support the wrapping and unwrapping of zero-length messages.<p>
671 *
672 * The format of the input token that this method
673 * reads is defined in the specification for the underlying mechanism that
674 * will be used. This method will attempt to read one of these tokens per
675 * invocation. If the mechanism token contains a definitive start and
676 * end this method may block on the <code>InputStream</code> if only
677 * part of the token is available. If the start and end of the token
678 * are not definitive then the method will attempt to treat all
679 * available bytes as part of the token.<p>
680 *
681 * Other than the possible blocking behaviour described above, this
682 * method is equivalent to the byte array based {@link #unwrap(byte[],
683 * int, int, MessageProp) unwrap} method.<p>
684 *
685 * @param inStream an InputStream that contains the wrap token generated
686 * by the peer.
687 * @param outStream an OutputStream to write the application message
688 * to.
689 * @param msgProp upon return from the method, this object will contain
690 * the applied QOP, the privacy state of the message, and supplementary
691 * information stating if the token was a duplicate, old, out of
692 * sequence or arriving after a gap.
693 *
694 * @throws GSSException containing the following
695 * major error codes:
696 * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
697 * {@link GSSException#BAD_MIC GSSException.BAD_MIC},
698 * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
699 * {@link GSSException#FAILURE GSSException.FAILURE}
700 */
701 public void unwrap(InputStream inStream, OutputStream outStream,
702 MessageProp msgProp) throws GSSException;
703
704 /**
705 * Returns a token containing a cryptographic Message Integrity Code
706 * (MIC) for the supplied message, for transfer to the peer
707 * application. Unlike wrap, which encapsulates the user message in the
708 * returned token, only the message MIC is returned in the output
709 * token.<p>
710 *
711 * Note that privacy can only be applied through the wrap call.<p>
712 *
713 * Since some application-level protocols may wish to use tokens emitted
714 * by getMIC to provide "secure framing", implementations should support
715 * derivation of MICs from zero-length messages.
716 *
717 * @param inMsg the message to generate the MIC over.
718 * @param offset offset within the inMsg where the message begins.
719 * @param len the length of the message
720 * @param msgProp an instance of <code>MessageProp</code> that is used
721 * by the application to set the desired QOP. Set the desired QOP to
722 * <code>0</code> in <code>msgProp</code> to request the default
723 * QOP. Alternatively pass in <code>null</code> for <code>msgProp</code>
724 * to request the default QOP.
725 * @return a byte[] containing the token to be sent to the peer.
726 *
727 * @throws GSSException containing the following
728 * major error codes:
729 * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
730 * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
731 * {@link GSSException#FAILURE GSSException.FAILURE}
732 */
733 public byte[] getMIC(byte []inMsg, int offset, int len,
734 MessageProp msgProp) throws GSSException;
735
736 /**
737 * Uses streams to produce a token containing a cryptographic MIC for
738 * the supplied message, for transfer to the peer application.
739 * Unlike wrap, which encapsulates the user message in the returned
740 * token, only the message MIC is produced in the output token. This
741 * method is equivalent to the byte array based {@link #getMIC(byte[],
742 * int, int, MessageProp) getMIC} method.
743 *
744 * Note that privacy can only be applied through the wrap call.<p>
745 *
746 * Since some application-level protocols may wish to use tokens emitted
747 * by getMIC to provide "secure framing", implementations should support
748 * derivation of MICs from zero-length messages.
749 *
750 * @param inStream an InputStream containing the message to generate the
751 * MIC over. All of the data that is available in
752 * inStream is used.
753 * @param outStream an OutputStream to write the output token to.
754 * @param msgProp an instance of <code>MessageProp</code> that is used
755 * by the application to set the desired QOP. Set the desired QOP to
756 * <code>0</code> in <code>msgProp</code> to request the default
757 * QOP. Alternatively pass in <code>null</code> for <code>msgProp</code>
758 * to request the default QOP.
759 *
760 * @throws GSSException containing the following
761 * major error codes:
762 * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
763 * {@link GSSException#BAD_QOP GSSException.BAD_QOP},
764 * {@link GSSException#FAILURE GSSException.FAILURE}
765 */
766 public void getMIC(InputStream inStream, OutputStream outStream,
767 MessageProp msgProp) throws GSSException;
768
769 /**
770 * Verifies the cryptographic MIC, contained in the token parameter,
771 * over the supplied message.<p>
772 *
773 * The MessageProp object is instantiated by the application and is used
774 * by the underlying mechanism to return information to the caller such
775 * as the QOP indicating the strength of protection that was applied to
776 * the message and other supplementary message state information.<p>
777 *
778 * Since some application-level protocols may wish to use tokens emitted
779 * by getMIC to provide "secure framing", implementations should support
780 * the calculation and verification of MICs over zero-length messages.
781 *
782 * @param inToken the token generated by peer's getMIC method.
783 * @param tokOffset the offset within the inToken where the token
784 * begins.
785 * @param tokLen the length of the token.
786 * @param inMsg the application message to verify the cryptographic MIC
787 * over.
788 * @param msgOffset the offset in inMsg where the message begins.
789 * @param msgLen the length of the message.
790 * @param msgProp upon return from the method, this object will contain
791 * the applied QOP and supplementary information stating if the token
792 * was a duplicate, old, out of sequence or arriving after a gap.
793 *
794 * @throws GSSException containing the following
795 * major error codes:
796 * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}
797 * {@link GSSException#BAD_MIC GSSException.BAD_MIC}
798 * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}
799 * {@link GSSException#FAILURE GSSException.FAILURE}
800 */
801 public void verifyMIC(byte[] inToken, int tokOffset, int tokLen,
802 byte[] inMsg, int msgOffset, int msgLen,
803 MessageProp msgProp) throws GSSException;
804
805 /**
806 * Uses streams to verify the cryptographic MIC, contained in the token
807 * parameter, over the supplied message. This method is equivalent to
808 * the byte array based {@link #verifyMIC(byte[], int, int, byte[], int,
809 * int, MessageProp) verifyMIC} method.
810 *
811 * The MessageProp object is instantiated by the application and is used
812 * by the underlying mechanism to return information to the caller such
813 * as the QOP indicating the strength of protection that was applied to
814 * the message and other supplementary message state information.<p>
815 *
816 * Since some application-level protocols may wish to use tokens emitted
817 * by getMIC to provide "secure framing", implementations should support
818 * the calculation and verification of MICs over zero-length messages.<p>
819 *
820 * The format of the input token that this method
821 * reads is defined in the specification for the underlying mechanism that
822 * will be used. This method will attempt to read one of these tokens per
823 * invocation. If the mechanism token contains a definitive start and
824 * end this method may block on the <code>InputStream</code> if only
825 * part of the token is available. If the start and end of the token
826 * are not definitive then the method will attempt to treat all
827 * available bytes as part of the token.<p>
828 *
829 * Other than the possible blocking behaviour described above, this
830 * method is equivalent to the byte array based {@link #verifyMIC(byte[],
831 * int, int, byte[], int, int, MessageProp) verifyMIC} method.<p>
832 *
833 * @param tokStream an InputStream containing the token generated by the
834 * peer's getMIC method.
835 * @param msgStream an InputStream containing the application message to
836 * verify the cryptographic MIC over. All of the data
837 * that is available in msgStream is used.
838 * @param msgProp upon return from the method, this object will contain
839 * the applied QOP and supplementary information stating if the token
840 * was a duplicate, old, out of sequence or arriving after a gap.
841 *
842 * @throws GSSException containing the following
843 * major error codes:
844 * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}
845 * {@link GSSException#BAD_MIC GSSException.BAD_MIC}
846 * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}
847 * {@link GSSException#FAILURE GSSException.FAILURE}
848 */
849 public void verifyMIC(InputStream tokStream, InputStream msgStream,
850 MessageProp msgProp) throws GSSException;
851
852 /**
853 * Exports this context so that another process may
854 * import it.. Provided to support the sharing of work between
855 * multiple processes. This routine will typically be used by the
856 * context-acceptor, in an application where a single process receives
857 * incoming connection requests and accepts security contexts over
858 * them, then passes the established context to one or more other
859 * processes for message exchange.<p>
860 *
861 * This method deactivates the security context and creates an
862 * interprocess token which, when passed to {@link
863 * GSSManager#createContext(byte[]) GSSManager.createContext} in
864 * another process, will re-activate the context in the second process.
865 * Only a single instantiation of a given context may be active at any
866 * one time; a subsequent attempt by a context exporter to access the
867 * exported security context will fail.<p>
868 *
869 * The implementation may constrain the set of processes by which the
870 * interprocess token may be imported, either as a function of local
871 * security policy, or as a result of implementation decisions. For
872 * example, some implementations may constrain contexts to be passed
873 * only between processes that run under the same account, or which are
874 * part of the same process group.<p>
875 *
876 * The interprocess token may contain security-sensitive information
877 * (for example cryptographic keys). While mechanisms are encouraged
878 * to either avoid placing such sensitive information within
879 * interprocess tokens, or to encrypt the token before returning it to
880 * the application, in a typical GSS-API implementation this may not be
881 * possible. Thus the application must take care to protect the
882 * interprocess token, and ensure that any process to which the token
883 * is transferred is trustworthy. <p>
884 *
885 * Implementations are not required to support the inter-process
886 * transfer of security contexts. Calling the {@link #isTransferable()
887 * isTransferable} method will indicate if the context object is
888 * transferable.<p>
889 *
890 * Calling this method on a context that
891 * is not exportable will result in this exception being thrown with
892 * the error code {@link GSSException#UNAVAILABLE
893 * GSSException.UNAVAILABLE}.
894 *
895 * @return a byte[] containing the exported context
896 * @see GSSManager#createContext(byte[])
897 *
898 * @throws GSSException containing the following
899 * major error codes:
900 * {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE},
901 * {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED},
902 * {@link GSSException#NO_CONTEXT GSSException.NO_CONTEXT},
903 * {@link GSSException#FAILURE GSSException.FAILURE}
904 */
905 public byte [] export() throws GSSException;
906
907 /**
908 * Requests that mutual authentication be done during
909 * context establishment. This request can only be made on the context
910 * initiator's side and it has to be done prior to the first call to
911 * <code>initSecContext</code>.<p>
912 *
913 * Not all mechanisms support mutual authentication and some mechanisms
914 * might require mutual authentication even if the application
915 * doesn't. Therefore, the application should check to see if the
916 * request was honored with the {@link #getMutualAuthState()
917 * getMutualAuthState} method.<p>
918 *
919 * @param state a boolean value indicating whether mutual
920 * authentication shouls be used or not.
921 * @see #getMutualAuthState()
922 *
923 * @throws GSSException containing the following
924 * major error codes:
925 * {@link GSSException#FAILURE GSSException.FAILURE}
926 */
927 public void requestMutualAuth(boolean state) throws GSSException;
928
929 /**
930 * Requests that replay detection be enabled for the
931 * per-message security services after context establishemnt. This
932 * request can only be made on the context initiator's side and it has
933 * to be done prior to the first call to
934 * <code>initSecContext</code>. During context establishment replay
935 * detection is not an option and is a function of the underlying
936 * mechanism's capabilities.<p>
937 *
938 * Not all mechanisms support replay detection and some mechanisms
939 * might require replay detection even if the application
940 * doesn't. Therefore, the application should check to see if the
941 * request was honored with the {@link #getReplayDetState()
942 * getReplayDetState} method. If replay detection is enabled then the
943 * {@link MessageProp#isDuplicateToken() MessageProp.isDuplicateToken} and {@link
944 * MessageProp#isOldToken() MessageProp.isOldToken} methods will return
945 * valid results for the <code>MessageProp</code> object that is passed
946 * in to the <code>unwrap</code> method or the <code>verifyMIC</code>
947 * method.<p>
948 *
949 * @param state a boolean value indicating whether replay detection
950 * should be enabled over the established context or not.
951 * @see #getReplayDetState()
952 *
953 * @throws GSSException containing the following
954 * major error codes:
955 * {@link GSSException#FAILURE GSSException.FAILURE}
956 */
957 public void requestReplayDet(boolean state) throws GSSException;
958
959 /**
960 * Requests that sequence checking be enabled for the
961 * per-message security services after context establishemnt. This
962 * request can only be made on the context initiator's side and it has
963 * to be done prior to the first call to
964 * <code>initSecContext</code>. During context establishment sequence
965 * checking is not an option and is a function of the underlying
966 * mechanism's capabilities.<p>
967 *
968 * Not all mechanisms support sequence checking and some mechanisms
969 * might require sequence checking even if the application
970 * doesn't. Therefore, the application should check to see if the
971 * request was honored with the {@link #getSequenceDetState()
972 * getSequenceDetState} method. If sequence checking is enabled then the
973 * {@link MessageProp#isDuplicateToken() MessageProp.isDuplicateToken},
974 * {@link MessageProp#isOldToken() MessageProp.isOldToken},
975 * {@link MessageProp#isUnseqToken() MessageProp.isUnseqToken}, and
976 * {@link MessageProp#isGapToken() MessageProp.isGapToken} methods will return
977 * valid results for the <code>MessageProp</code> object that is passed
978 * in to the <code>unwrap</code> method or the <code>verifyMIC</code>
979 * method.<p>
980 *
981 * @param state a boolean value indicating whether sequence checking
982 * should be enabled over the established context or not.
983 * @see #getSequenceDetState()
984 *
985 * @throws GSSException containing the following
986 * major error codes:
987 * {@link GSSException#FAILURE GSSException.FAILURE}
988 */
989 public void requestSequenceDet(boolean state) throws GSSException;
990
991 /**
992 * Requests that the initiator's credentials be
993 * delegated to the acceptor during context establishment. This
994 * request can only be made on the context initiator's side and it has
995 * to be done prior to the first call to
996 * <code>initSecContext</code>.
997 *
998 * Not all mechanisms support credential delegation. Therefore, an
999 * application that desires delegation should check to see if the
1000 * request was honored with the {@link #getCredDelegState()
1001 * getCredDelegState} method. If the application indicates that
1002 * delegation must not be used, then the mechanism will honor the
1003 * request and delegation will not occur. This is an exception
1004 * to the general rule that a mechanism may enable a service even if it
1005 * is not requested.<p>
1006 *
1007 * @param state a boolean value indicating whether the credentials
1008 * should be delegated or not.
1009 * @see #getCredDelegState()
1010 *
1011 * @throws GSSException containing the following
1012 * major error codes:
1013 * {@link GSSException#FAILURE GSSException.FAILURE}
1014 */
1015 public void requestCredDeleg(boolean state) throws GSSException;
1016
1017 /**
1018 * Requests that the initiator's identity not be
1019 * disclosed to the acceptor. This request can only be made on the
1020 * context initiator's side and it has to be done prior to the first
1021 * call to <code>initSecContext</code>.
1022 *
1023 * Not all mechanisms support anonymity for the initiator. Therefore, the
1024 * application should check to see if the request was honored with the
1025 * {@link #getAnonymityState() getAnonymityState} method.<p>
1026 *
1027 * @param state a boolean value indicating if the initiator should
1028 * be authenticated to the acceptor as an anonymous principal.
1029 * @see #getAnonymityState
1030 *
1031 * @throws GSSException containing the following
1032 * major error codes:
1033 * {@link GSSException#FAILURE GSSException.FAILURE}
1034 */
1035 public void requestAnonymity(boolean state) throws GSSException;
1036
1037 /**
1038 * Requests that data confidentiality be enabled
1039 * for the <code>wrap</code> method. This request can only be made on
1040 * the context initiator's side and it has to be done prior to the
1041 * first call to <code>initSecContext</code>.
1042 *
1043 * Not all mechanisms support confidentiality and other mechanisms
1044 * might enable it even if the application doesn't request
1045 * it. The application may check to see if the request was honored with
1046 * the {@link #getConfState() getConfState} method. If confidentiality
1047 * is enabled, only then will the mechanism honor a request for privacy
1048 * in the {@link MessageProp#MessageProp(int, boolean) MessageProp}
1049 * object that is passed in to the <code>wrap</code> method.<p>
1050 *
1051 * Enabling confidentiality will also automatically enable
1052 * integrity.<p>
1053 *
1054 * @param state a boolean value indicating whether confidentiality
1055 * should be enabled or not.
1056 * @see #getConfState()
1057 * @see #getIntegState()
1058 * @see #requestInteg(boolean)
1059 * @see MessageProp
1060 *
1061 * @throws GSSException containing the following
1062 * major error codes:
1063 * {@link GSSException#FAILURE GSSException.FAILURE}
1064 */
1065 public void requestConf(boolean state) throws GSSException;
1066
1067 /**
1068 * Requests that data integrity be enabled
1069 * for the <code>wrap</code> and <code>getMIC</code>methods. This
1070 * request can only be made on the context initiator's side and it has
1071 * to be done prior to the first call to <code>initSecContext</code>.
1072 *
1073 * Not all mechanisms support integrity and other mechanisms
1074 * might enable it even if the application doesn't request
1075 * it. The application may check to see if the request was honored with
1076 * the {@link #getIntegState() getIntegState} method.<p>
1077 *
1078 * Disabling integrity will also automatically disable
1079 * confidentiality.<p>
1080 *
1081 * @param state a boolean value indicating whether integrity
1082 * should be enabled or not.
1083 * @see #getIntegState()
1084 *
1085 * @throws GSSException containing the following
1086 * major error codes:
1087 * {@link GSSException#FAILURE GSSException.FAILURE}
1088 */
1089 public void requestInteg(boolean state) throws GSSException;
1090
1091 /**
1092 * Requests a lifetime in seconds for the
1093 * context. This method can only be called on the context initiator's
1094 * side and it has to be done prior to the first call to
1095 * <code>initSecContext</code>.<p>
1096 *
1097 * The actual lifetime of the context will depend on the capabilites of
1098 * the underlying mechanism and the application should call the {@link
1099 * #getLifetime() getLifetime} method to determine this.<p>
1100 *
1101 * @param lifetime the desired context lifetime in seconds. Use
1102 * <code>INDEFINITE_LIFETIME</code> to request an indefinite lifetime
1103 * and <code>DEFAULT_LIFETIME</code> to request a default lifetime.
1104 * @see #getLifetime()
1105 *
1106 * @throws GSSException containing the following
1107 * major error codes:
1108 * {@link GSSException#FAILURE GSSException.FAILURE}
1109 */
1110 public void requestLifetime(int lifetime) throws GSSException;
1111
1112 /**
1113 * Sets the channel bindings to be used during context
1114 * establishment. This method can be called on both
1115 * the context initiator's and the context acceptor's side, but it must
1116 * be called before context establishment begins. This means that an
1117 * initiator must call it before the first call to
1118 * <code>initSecContext</code> and the acceptor must call it before the
1119 * first call to <code>acceptSecContext</code>.
1120 *
1121 * @param cb the channel bindings to use.
1122 *
1123 * @throws GSSException containing the following
1124 * major error codes:
1125 * {@link GSSException#FAILURE GSSException.FAILURE}
1126 */
1127 public void setChannelBinding(ChannelBinding cb) throws GSSException;
1128
1129 /**
1130 * Determines if credential delegation is enabled on
1131 * this context. It can be called by both the context initiator and the
1132 * context acceptor. For a definitive answer this method must be
1133 * called only after context establishment is complete. Note that if an
1134 * initiator requests that delegation not be allowed the {@link
1135 * #requestCredDeleg(boolean) requestCredDeleg} method will honor that
1136 * request and this method will return <code>false</code> on the
1137 * initiator's side from that point onwards. <p>
1138 *
1139 * @return true if delegation is enabled, false otherwise.
1140 * @see #requestCredDeleg(boolean)
1141 */
1142 public boolean getCredDelegState();
1143
1144 /**
1145 * Determines if mutual authentication is enabled on
1146 * this context. It can be called by both the context initiator and the
1147 * context acceptor. For a definitive answer this method must be
1148 * called only after context establishment is complete. An initiator
1149 * that requests mutual authentication can call this method after
1150 * context completion and dispose the context if its request was not
1151 * honored.<p>
1152 *
1153 * @return true if mutual authentication is enabled, false otherwise.
1154 * @see #requestMutualAuth(boolean)
1155 */
1156 public boolean getMutualAuthState();
1157
1158 /**
1159 * Determines if replay detection is enabled for the
1160 * per-message security services from this context. It can be called by
1161 * both the context initiator and the context acceptor. For a
1162 * definitive answer this method must be called only after context
1163 * establishment is complete. An initiator that requests replay
1164 * detection can call this method after context completion and
1165 * dispose the context if its request was not honored.<p>
1166 *
1167 * @return true if replay detection is enabled, false otherwise.
1168 * @see #requestReplayDet(boolean)
1169 */
1170 public boolean getReplayDetState();
1171
1172 /**
1173 * Determines if sequence checking is enabled for the
1174 * per-message security services from this context. It can be called by
1175 * both the context initiator and the context acceptor. For a
1176 * definitive answer this method must be called only after context
1177 * establishment is complete. An initiator that requests sequence
1178 * checking can call this method after context completion and
1179 * dispose the context if its request was not honored.<p>
1180 *
1181 * @return true if sequence checking is enabled, false otherwise.
1182 * @see #requestSequenceDet(boolean)
1183 */
1184 public boolean getSequenceDetState();
1185
1186 /**
1187 * Determines if the context initiator is
1188 * anonymously authenticated to the context acceptor. It can be called by
1189 * both the context initiator and the context acceptor, and at any
1190 * time. <strong>On the initiator side, a call to this method determines
1191 * if the identity of the initiator has been disclosed in any of the
1192 * context establishment tokens that might have been generated thus far
1193 * by <code>initSecContext</code>. An initiator that absolutely must be
1194 * authenticated anonymously should call this method after each call to
1195 * <code>initSecContext</code> to determine if the generated token
1196 * should be sent to the peer or the context aborted.</strong> On the
1197 * acceptor side, a call to this method determines if any of the tokens
1198 * processed by <code>acceptSecContext</code> thus far have divulged
1199 * the identity of the initiator.<p>
1200 *
1201 * @return true if the context initiator is still anonymous, false
1202 * otherwise.
1203 * @see #requestAnonymity(boolean)
1204 */
1205 public boolean getAnonymityState();
1206
1207 /**
1208 * Determines if the context is transferable to other processes
1209 * through the use of the {@link #export() export} method. This call
1210 * is only valid on fully established contexts.
1211 *
1212 * @return true if this context can be exported, false otherwise.
1213 *
1214 * @throws GSSException containing the following
1215 * major error codes:
1216 * {@link GSSException#FAILURE GSSException.FAILURE}
1217 */
1218 public boolean isTransferable() throws GSSException;
1219
1220 /**
1221 * Determines if the context is ready for per message operations to be
1222 * used over it. Some mechanisms may allow the usage of the
1223 * per-message operations before the context is fully established.
1224 *
1225 * @return true if methods like <code>wrap</code>, <code>unwrap</code>,
1226 * <code>getMIC</code>, and <code>verifyMIC</code> can be used with
1227 * this context at the current stage of context establishment, false
1228 * otherwise.
1229 */
1230 public boolean isProtReady();
1231
1232 /**
1233 * Determines if data confidentiality is available
1234 * over the context. This method can be called by both the context
1235 * initiator and the context acceptor, but only after one of {@link
1236 * #isProtReady() isProtReady} or {@link #isEstablished()
1237 * isEstablished} return <code>true</code>. If this method returns
1238 * <code>true</code>, so will {@link #getIntegState()
1239 * getIntegState}<p>
1240 *
1241 * @return true if confidentiality services are available, false
1242 * otherwise.
1243 * @see #requestConf(boolean)
1244 */
1245 public boolean getConfState();
1246
1247 /**
1248 * Determines if data integrity is available
1249 * over the context. This method can be called by both the context
1250 * initiator and the context acceptor, but only after one of {@link
1251 * #isProtReady() isProtReady} or {@link #isEstablished()
1252 * isEstablished} return <code>true</code>. This method will always
1253 * return <code>true</code> if {@link #getConfState() getConfState}
1254 * returns true.<p>
1255 *
1256 * @return true if integrity services are available, false otherwise.
1257 * @see #requestInteg(boolean)
1258 */
1259 public boolean getIntegState();
1260
1261 /**
1262 * Determines what the remaining lifetime for this
1263 * context is. It can be called by both the context initiator and the
1264 * context acceptor, but for a definitive answer it should be called
1265 * only after {@link #isEstablished() isEstablished} returns
1266 * true.<p>
1267 *
1268 * @return the remaining lifetime in seconds
1269 * @see #requestLifetime(int)
1270 */
1271 public int getLifetime();
1272
1273 /**
1274 * Returns the name of the context initiator. This call is valid only
1275 * after one of {@link #isProtReady() isProtReady} or {@link
1276 * #isEstablished() isEstablished} return <code>true</code>.
1277 *
1278 * @return a GSSName that is an MN containing the name of the context
1279 * initiator.
1280 * @see GSSName
1281 *
1282 * @throws GSSException containing the following
1283 * major error codes:
1284 * {@link GSSException#FAILURE GSSException.FAILURE}
1285 */
1286 public GSSName getSrcName() throws GSSException;
1287
1288 /**
1289 * Returns the name of the context acceptor. This call is valid only
1290 * after one of {@link #isProtReady() isProtReady} or {@link
1291 * #isEstablished() isEstablished} return <code>true</code>.
1292 *
1293 * @return a GSSName that is an MN containing the name of the context
1294 * acceptor.
1295 *
1296 * @throws GSSException containing the following
1297 * major error codes:
1298 * {@link GSSException#FAILURE GSSException.FAILURE}
1299 */
1300 public GSSName getTargName() throws GSSException;
1301
1302 /**
1303 * Determines what mechanism is being used for this
1304 * context. This method may be called before the context is fully
1305 * established, but the mechanism returned may change on successive
1306 * calls in the negotiated mechanism case.
1307 *
1308 * @return the Oid of the mechanism being used
1309 *
1310 * @throws GSSException containing the following
1311 * major error codes:
1312 * {@link GSSException#FAILURE GSSException.FAILURE}
1313 */
1314 public Oid getMech() throws GSSException;
1315
1316 /**
1317 * Obtains the credentials delegated by the context
1318 * initiator to the context acceptor. It should be called only on the
1319 * context acceptor's side, and once the context is fully
1320 * established. The caller can use the method {@link
1321 * #getCredDelegState() getCredDelegState} to determine if there are
1322 * any delegated credentials.
1323 *
1324 * @return a GSSCredential containing the initiator's delegated
1325 * credentials, or <code>null</code> is no credentials
1326 * were delegated.
1327 *
1328 * @throws GSSException containing the following
1329 * major error codes:
1330 * {@link GSSException#FAILURE GSSException.FAILURE}
1331 */
1332 public GSSCredential getDelegCred() throws GSSException;
1333
1334 /**
1335 * Determines if this is the context initiator. This
1336 * can be called on both the context initiator's and context acceptor's
1337 * side.
1338 *
1339 * @return true if this is the context initiator, false if it is the
1340 * context acceptor.
1341 *
1342 * @throws GSSException containing the following
1343 * major error codes:
1344 * {@link GSSException#FAILURE GSSException.FAILURE}
1345 */
1346 public boolean isInitiator() throws GSSException;
1347 }
Save This Page