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