1 /*
2 * Copyright (c) 2000, 2013, 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.security.Provider;
29
30 /**
31 * This class serves as a factory for other important
32 * GSS-API classes and also provides information about the mechanisms that
33 * are supported. It can create instances of classes
34 * implementing the following three GSS-API interfaces: {@link
35 * GSSName GSSName}, {@link GSSCredential GSSCredential}, and {@link
36 * GSSContext GSSContext}. It also has methods to query for the list
37 * of available mechanisms and the nametypes that each mechanism
38 * supports.<p>
39 *
40 * An instance of the default <code>GSSManager</code> subclass
41 * may be obtained through the static method {@link #getInstance()
42 * getInstance}, but applications are free to instantiate other subclasses
43 * of <code>GSSManager</code>. The default <code>GSSManager</code> instance
44 * will support the Kerberos v5 GSS-API mechanism in addition to any
45 * others. This mechanism is identified by the Oid "1.2.840.113554.1.2.2"
46 * and is defined in RFC 1964.<p>
47 *
48 * A subclass extending the <code>GSSManager</code> abstract class may be
49 * implemented as a modular provider based layer that utilizes some well
50 * known service provider specification. The <code>GSSManager</code> API
51 * allows the application to set provider preferences on
52 * such an implementation. These methods also allow the implementation to
53 * throw a well-defined exception in case provider based configuration is
54 * not supported. Applications that expect to be portable should be aware
55 * of this and recover cleanly by catching the exception.<p>
56 *
57 * It is envisioned that there will be three most common ways in which
58 * providers will be used:<p>
59 * <ol>
60 * <li> The application does not care about what provider is used (the
61 * default case).
62 * <li> The application wants a particular provider to be used
63 * preferentially, either for a particular mechanism or all the
64 * time, irrespective of mechanism.
65 * <li> The application wants to use the locally configured providers
66 * as far as possible but if support is missing for one or more
67 * mechanisms then it wants to fall back on its own provider.
68 *</ol><p>
69 *
70 * The <code>GSSManager</code> class has two methods that enable these modes of
71 * usage: {@link #addProviderAtFront(Provider, Oid) addProviderAtFront} and
72 * {@link #addProviderAtEnd(Provider, Oid) addProviderAtEnd}. These methods
73 * have the effect of creating an ordered list of <i><provider,
74 * oid></i> pairs where each pair indicates a preference of provider
75 * for a given oid.<p>
76 *
77 * It is important to note that there are certain interactions
78 * between the different GSS-API objects that are created by a
79 * GSSManager, where the provider that is used for a particular mechanism
80 * might need to be consistent across all objects. For instance, if a
81 * GSSCredential contains elements from a provider <i>p</i> for a mechanism
82 * <i>m</i>, it should generally be passed in to a GSSContext that will use
83 * provider <i>p</i> for the mechanism <i>m</i>. A simple rule of thumb
84 * that will maximize portability is that objects created from different
85 * GSSManager's should not be mixed, and if possible, a different
86 * GSSManager instance should be created if the application wants to invoke
87 * the <code>addProviderAtFront</code> method on a GSSManager that has
88 * already created an object.<p>
89 *
90 * Here is some sample code showing how the GSSManager might be used: <p>
91 * <pre>
92 * GSSManager manager = GSSManager.getInstance();
93 *
94 * Oid krb5Mechanism = new Oid("1.2.840.113554.1.2.2");
95 * Oid krb5PrincipalNameType = new Oid("1.2.840.113554.1.2.2.1");
96 *
97 * // Identify who the client wishes to be
98 * GSSName userName = manager.createName("duke", GSSName.NT_USER_NAME);
99 *
100 * // Identify the name of the server. This uses a Kerberos specific
101 * // name format.
102 * GSSName serverName = manager.createName("nfs/foo.sun.com",
103 * krb5PrincipalNameType);
104 *
105 * // Acquire credentials for the user
106 * GSSCredential userCreds = manager.createCredential(userName,
107 * GSSCredential.DEFAULT_LIFETIME,
108 * krb5Mechanism,
109 * GSSCredential.INITIATE_ONLY);
110 *
111 * // Instantiate and initialize a security context that will be
112 * // established with the server
113 * GSSContext context = manager.createContext(serverName,
114 * krb5Mechanism,
115 * userCreds,
116 * GSSContext.DEFAULT_LIFETIME);
117 * </pre><p>
118 *
119 * The server side might use the following variation of this source:<p>
120 *
121 * <pre>
122 * // Acquire credentials for the server
123 * GSSCredential serverCreds = manager.createCredential(serverName,
124 * GSSCredential.DEFAULT_LIFETIME,
125 * krb5Mechanism,
126 * GSSCredential.ACCEPT_ONLY);
127 *
128 * // Instantiate and initialize a security context that will
129 * // wait for an establishment request token from the client
130 * GSSContext context = manager.createContext(serverCreds);
131 * </pre>
132 *
133 * @author Mayank Upadhyay
134 * @see GSSName
135 * @see GSSCredential
136 * @see GSSContext
137 * @since 1.4
138 */
139 public abstract class GSSManager {
140
141 /**
142 * Returns the default GSSManager implementation.
143 *
144 * @return a GSSManager implementation
145 */
146 public static GSSManager getInstance() {
147 return new sun.security.jgss.GSSManagerImpl();
148 }
149
150 /**
151 * Returns a list of mechanisms that are available to GSS-API callers
152 * through this GSSManager. The default GSSManager obtained from the
153 * {@link #getInstance() getInstance()} method includes the Oid
154 * "1.2.840.113554.1.2.2" in its list. This Oid identifies the Kerberos
155 * v5 GSS-API mechanism that is defined in RFC 1964.
156 *
157 * @return an array of Oid objects corresponding to the mechanisms that
158 * are available. A <code>null</code> value is returned when no
159 * mechanism are available (an example of this would be when mechanism
160 * are dynamically configured, and currently no mechanisms are
161 * installed).
162 */
163 public abstract Oid[] getMechs();
164
165 /**
166 * Returns then name types supported by the indicated mechanism.<p>
167 *
168 * The default GSSManager instance includes support for the Kerberos v5
169 * mechanism. When this mechanism ("1.2.840.113554.1.2.2") is indicated,
170 * the returned list will contain at least the following nametypes:
171 * {@link GSSName#NT_HOSTBASED_SERVICE GSSName.NT_HOSTBASED_SERVICE},
172 * {@link GSSName#NT_EXPORT_NAME GSSName.NT_EXPORT_NAME}, and the
173 * Kerberos v5 specific Oid "1.2.840.113554.1.2.2.1". The namespace for
174 * the Oid "1.2.840.113554.1.2.2.1" is defined in RFC 1964.
175 *
176 * @return an array of Oid objects corresponding to the name types that
177 * the mechanism supports.
178 * @param mech the Oid of the mechanism to query
179 *
180 * @see #getMechsForName(Oid)
181 *
182 * @throws GSSException containing the following
183 * major error codes:
184 * {@link GSSException#BAD_MECH GSSException.BAD_MECH}
185 * {@link GSSException#FAILURE GSSException.FAILURE}
186 */
187 public abstract Oid[] getNamesForMech(Oid mech)
188 throws GSSException;
189
190 /**
191 * Returns a list of mechanisms that support the indicated name type.<p>
192 *
193 * The Kerberos v5 mechanism ("1.2.840.113554.1.2.2") will always be
194 * returned in this list when the indicated nametype is one of
195 * {@link GSSName#NT_HOSTBASED_SERVICE GSSName.NT_HOSTBASED_SERVICE},
196 * {@link GSSName#NT_EXPORT_NAME GSSName.NT_EXPORT_NAME}, or
197 * "1.2.840.113554.1.2.2.1".
198 *
199 * @return an array of Oid objects corresponding to the mechanisms that
200 * support the specified name type. <code>null</code> is returned when no
201 * mechanisms are found to support the specified name type.
202 * @param nameType the Oid of the name type to look for
203 *
204 * @see #getNamesForMech(Oid)
205 */
206 public abstract Oid[] getMechsForName(Oid nameType);
207
208 /**
209 * Factory method to convert a string name from the
210 * specified namespace to a GSSName object. In general, the
211 * <code>GSSName</code> object created will contain multiple
212 * representations of the name, one for each mechanism that is
213 * supported; two examples that are exceptions to this are when
214 * the namespace type parameter indicates NT_EXPORT_NAME or when the
215 * GSS-API implementation is not multi-mechanism. It is
216 * not recommended to use this method with a NT_EXPORT_NAME type because
217 * representing a previously exported name consisting of arbitrary bytes
218 * as a String might cause problems with character encoding schemes. In
219 * such cases it is recommended that the bytes be passed in directly to
220 * the overloaded form of this method {@link #createName(byte[],
221 * Oid) createName}.
222 *
223 * @param nameStr the string representing a printable form of the name to
224 * create.
225 * @param nameType the Oid specifying the namespace of the printable name
226 * supplied. <code>null</code> can be used to specify
227 * that a mechanism specific default printable syntax should
228 * be assumed by each mechanism that examines nameStr.
229 * It is not advisable to use the nametype NT_EXPORT_NAME with this
230 * method.
231 * @return a GSSName representing the indicated principal
232 *
233 * @see GSSName
234 * @see GSSName#NT_EXPORT_NAME
235 *
236 * @throws GSSException containing the following
237 * major error codes:
238 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
239 * {@link GSSException#BAD_NAME GSSException.BAD_NAME},
240 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
241 * {@link GSSException#FAILURE GSSException.FAILURE}
242 */
243 public abstract GSSName createName(String nameStr, Oid nameType)
244 throws GSSException;
245
246 /**
247 * Factory method to convert a byte array containing a
248 * name from the specified namespace to a GSSName object. In general,
249 * the <code>GSSName</code> object created will contain multiple
250 * representations of the name, one for each mechanism that is
251 * supported; two examples that are exceptions to this are when the
252 * namespace type parameter indicates NT_EXPORT_NAME or when the
253 * GSS-API implementation is not multi-mechanism. The bytes that are
254 * passed in are interpreted by each underlying mechanism according to
255 * some encoding scheme of its choice for the given nametype.
256 *
257 * @param name the byte array containing the name to create
258 * @param nameType the Oid specifying the namespace of the name supplied
259 * in the byte array. <code>null</code> can be used to specify that a
260 * mechanism specific default syntax should be assumed by each mechanism
261 * that examines the byte array.
262 * @return a GSSName representing the indicated principal
263 *
264 * @see GSSName
265 * @see GSSName#NT_EXPORT_NAME
266 *
267 * @throws GSSException containing the following
268 * major error codes:
269 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
270 * {@link GSSException#BAD_NAME GSSException.BAD_NAME},
271 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
272 * {@link GSSException#FAILURE GSSException.FAILURE}
273 */
274 public abstract GSSName createName(byte name[], Oid nameType)
275 throws GSSException;
276
277 /**
278 * Factory method to convert a string name from the
279 * specified namespace to a GSSName object and canonicalize it at the
280 * same time for a mechanism. In other words, this method is
281 * a utility that does the equivalent of two steps: the {@link
282 * #createName(String, Oid) createName} and then also the {@link
283 * GSSName#canonicalize(Oid) GSSName.canonicalize}.
284 *
285 * @param nameStr the string representing a printable form of the name to
286 * create.
287 * @param nameType the Oid specifying the namespace of the printable name
288 * supplied. <code>null</code> can be used to specify
289 * that a mechanism specific default printable syntax should
290 * be assumed by each mechanism that examines nameStr.
291 * It is not advisable to use the nametype NT_EXPORT_NAME with this
292 * method.
293 * @param mech Oid specifying the mechanism for which the name should be
294 * canonicalized
295 * @return a GSSName representing the indicated principal
296 *
297 * @see GSSName#canonicalize(Oid)
298 * @see GSSName#NT_EXPORT_NAME
299 *
300 * @throws GSSException containing the following
301 * major error codes:
302 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
303 * {@link GSSException#BAD_NAME GSSException.BAD_NAME},
304 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
305 * {@link GSSException#FAILURE GSSException.FAILURE}
306 */
307 public abstract GSSName createName(String nameStr, Oid nameType,
308 Oid mech) throws GSSException;
309
310 /**
311 * Factory method to convert a byte array containing a
312 * name from the specified namespace to a GSSName object and canonicalize
313 * it at the same time for a mechanism. In other words, this method is a
314 * utility that does the equivalent of two steps: the {@link
315 * #createName(byte[], Oid) createName} and then also {@link
316 * GSSName#canonicalize(Oid) GSSName.canonicalize}.
317 *
318 * @param name the byte array containing the name to create
319 * @param nameType the Oid specifying the namespace of the name supplied
320 * in the byte array. <code>null</code> can be used to specify that a
321 * mechanism specific default syntax should be assumed by each mechanism
322 * that examines the byte array.
323 * @param mech Oid specifying the mechanism for which the name should be
324 * canonicalized
325 * @return a GSSName representing the indicated principal
326 *
327 * @see GSSName#canonicalize(Oid)
328 * @see GSSName#NT_EXPORT_NAME
329 *
330 * @throws GSSException containing the following
331 * major error codes:
332 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
333 * {@link GSSException#BAD_NAME GSSException.BAD_NAME},
334 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
335 * {@link GSSException#FAILURE GSSException.FAILURE}
336 */
337 public abstract GSSName createName(byte name[], Oid nameType, Oid mech)
338 throws GSSException;
339
340 /**
341 * Factory method for acquiring default credentials. This will cause
342 * the GSS-API to use system specific defaults for the set of mechanisms,
343 * name, and lifetime.<p>
344 *
345 * GSS-API mechanism providers must impose a local access-control
346 * policy on callers to prevent unauthorized callers from acquiring
347 * credentials to which they are not entitled. The kinds of permissions
348 * needed by different mechanism providers will be documented on a
349 * per-mechanism basis. A failed permission check might cause a {@link
350 * java.lang.SecurityException SecurityException} to be thrown from
351 * this method.
352 *
353 * @param usage The intended usage for this credential object. The value
354 * of this parameter must be one of:
355 * {@link GSSCredential#INITIATE_AND_ACCEPT
356 * GSSCredential.INITIATE_AND_ACCEPT},
357 * {@link GSSCredential#ACCEPT_ONLY GSSCredential.ACCEPT_ONLY}, and
358 * {@link GSSCredential#INITIATE_ONLY GSSCredential.INITIATE_ONLY}.
359 * @return a GSSCredential of the requested type.
360 *
361 * @see GSSCredential
362 *
363 * @throws GSSException containing the following
364 * major error codes:
365 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
366 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
367 * {@link GSSException#BAD_NAME GSSException.BAD_NAME},
368 * {@link GSSException#CREDENTIALS_EXPIRED
369 * GSSException.CREDENTIALS_EXPIRED},
370 * {@link GSSException#NO_CRED GSSException.NO_CRED},
371 * {@link GSSException#FAILURE GSSException.FAILURE}
372 */
373 public abstract GSSCredential createCredential (int usage)
374 throws GSSException;
375
376 /**
377 * Factory method for acquiring a single mechanism credential.<p>
378 *
379 * GSS-API mechanism providers must impose a local access-control
380 * policy on callers to prevent unauthorized callers from acquiring
381 * credentials to which they are not entitled. The kinds of permissions
382 * needed by different mechanism providers will be documented on a
383 * per-mechanism basis. A failed permission check might cause a {@link
384 * java.lang.SecurityException SecurityException} to be thrown from
385 * this method. <p>
386 *
387 * Non-default values for lifetime cannot always be honored by the
388 * underlying mechanisms, thus applications should be prepared to call
389 * {@link GSSCredential#getRemainingLifetime() getRemainingLifetime}
390 * on the returned credential.<p>
391 *
392 * @param name the name of the principal for whom this credential is to be
393 * acquired. Use <code>null</code> to specify the default principal.
394 * @param lifetime The number of seconds that credentials should remain
395 * valid. Use {@link GSSCredential#INDEFINITE_LIFETIME
396 * GSSCredential.INDEFINITE_LIFETIME} to request that the credentials
397 * have the maximum permitted lifetime. Use {@link
398 * GSSCredential#DEFAULT_LIFETIME GSSCredential.DEFAULT_LIFETIME} to
399 * request default credential lifetime.
400 * @param mech the Oid of the desired mechanism. Use <code>(Oid) null
401 * </code> to request the default mechanism.
402 * @param usage The intended usage for this credential object. The value
403 * of this parameter must be one of:
404 * {@link GSSCredential#INITIATE_AND_ACCEPT
405 * GSSCredential.INITIATE_AND_ACCEPT},
406 * {@link GSSCredential#ACCEPT_ONLY GSSCredential.ACCEPT_ONLY}, and
407 * {@link GSSCredential#INITIATE_ONLY GSSCredential.INITIATE_ONLY}.
408 * @return a GSSCredential of the requested type.
409 *
410 * @see GSSCredential
411 *
412 * @throws GSSException containing the following
413 * major error codes:
414 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
415 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
416 * {@link GSSException#BAD_NAME GSSException.BAD_NAME},
417 * {@link GSSException#CREDENTIALS_EXPIRED
418 * GSSException.CREDENTIALS_EXPIRED},
419 * {@link GSSException#NO_CRED GSSException.NO_CRED},
420 * {@link GSSException#FAILURE GSSException.FAILURE}
421 */
422 public abstract GSSCredential createCredential (GSSName name,
423 int lifetime, Oid mech, int usage)
424 throws GSSException;
425
426 /**
427 * Factory method for acquiring credentials over a set of
428 * mechanisms. This method attempts to acquire credentials for
429 * each of the mechanisms specified in the array called mechs. To
430 * determine the list of mechanisms for which the acquisition of
431 * credentials succeeded, the caller should use the {@link
432 * GSSCredential#getMechs() GSSCredential.getMechs} method.<p>
433 *
434 * GSS-API mechanism providers must impose a local access-control
435 * policy on callers to prevent unauthorized callers from acquiring
436 * credentials to which they are not entitled. The kinds of permissions
437 * needed by different mechanism providers will be documented on a
438 * per-mechanism basis. A failed permission check might cause a {@link
439 * java.lang.SecurityException SecurityException} to be thrown from
440 * this method.<p>
441 *
442 * Non-default values for lifetime cannot always be honored by the
443 * underlying mechanisms, thus applications should be prepared to call
444 * {@link GSSCredential#getRemainingLifetime() getRemainingLifetime}
445 * on the returned credential.<p>
446 *
447 * @param name the name of the principal for whom this credential is to
448 * be acquired. Use <code>null</code> to specify the default
449 * principal.
450 * @param lifetime The number of seconds that credentials should remain
451 * valid. Use {@link GSSCredential#INDEFINITE_LIFETIME
452 * GSSCredential.INDEFINITE_LIFETIME} to request that the credentials
453 * have the maximum permitted lifetime. Use {@link
454 * GSSCredential#DEFAULT_LIFETIME GSSCredential.DEFAULT_LIFETIME} to
455 * request default credential lifetime.
456 * @param mechs an array of Oid's indicating the mechanisms over which
457 * the credential is to be acquired. Use <code>(Oid[]) null</code> for
458 * requesting a system specific default set of mechanisms.
459 * @param usage The intended usage for this credential object. The value
460 * of this parameter must be one of:
461 * {@link GSSCredential#INITIATE_AND_ACCEPT
462 * GSSCredential.INITIATE_AND_ACCEPT},
463 * {@link GSSCredential#ACCEPT_ONLY GSSCredential.ACCEPT_ONLY}, and
464 * {@link GSSCredential#INITIATE_ONLY GSSCredential.INITIATE_ONLY}.
465 * @return a GSSCredential of the requested type.
466 *
467 * @see GSSCredential
468 *
469 * @throws GSSException containing the following
470 * major error codes:
471 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
472 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
473 * {@link GSSException#BAD_NAME GSSException.BAD_NAME},
474 * {@link GSSException#CREDENTIALS_EXPIRED
475 * GSSException.CREDENTIALS_EXPIRED},
476 * {@link GSSException#NO_CRED GSSException.NO_CRED},
477 * {@link GSSException#FAILURE GSSException.FAILURE}
478 */
479 public abstract GSSCredential createCredential(GSSName name,
480 int lifetime, Oid mechs[], int usage)
481 throws GSSException;
482
483 /**
484 * Factory method for creating a context on the initiator's
485 * side.
486 *
487 * Some mechanism providers might require that the caller be granted
488 * permission to initiate a security context. A failed permission check
489 * might cause a {@link java.lang.SecurityException SecurityException}
490 * to be thrown from this method.<p>
491 *
492 * Non-default values for lifetime cannot always be honored by the
493 * underlying mechanism, thus applications should be prepared to call
494 * {@link GSSContext#getLifetime() getLifetime} on the returned
495 * context.<p>
496 *
497 * @param peer the name of the target peer.
498 * @param mech the Oid of the desired mechanism. Use <code>null</code>
499 * to request the default mechanism.
500 * @param myCred the credentials of the initiator. Use
501 * <code>null</code> to act as the default initiator principal.
502 * @param lifetime the lifetime, in seconds, requested for the
503 * context. Use {@link GSSContext#INDEFINITE_LIFETIME
504 * GSSContext.INDEFINITE_LIFETIME} to request that the context have the
505 * maximum permitted lifetime. Use {@link GSSContext#DEFAULT_LIFETIME
506 * GSSContext.DEFAULT_LIFETIME} to request a default lifetime for the
507 * context.
508 * @return an unestablished GSSContext
509 *
510 * @see GSSContext
511 *
512 * @throws GSSException containing the following
513 * major error codes:
514 * {@link GSSException#NO_CRED GSSException.NO_CRED}
515 * {@link GSSException#CREDENTIALS_EXPIRED
516 * GSSException.CREDENTIALS_EXPIRED}
517 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE}
518 * {@link GSSException#BAD_MECH GSSException.BAD_MECH}
519 * {@link GSSException#FAILURE GSSException.FAILURE}
520 */
521 public abstract GSSContext createContext(GSSName peer, Oid mech,
522 GSSCredential myCred, int lifetime)
523 throws GSSException;
524
525 /**
526 * Factory method for creating a context on the acceptor' side. The
527 * context's properties will be determined from the input token supplied
528 * to the accept method.
529 *
530 * Some mechanism providers might require that the caller be granted
531 * permission to accept a security context. A failed permission check
532 * might cause a {@link java.lang.SecurityException SecurityException}
533 * to be thrown from this method.
534 *
535 * @param myCred the credentials for the acceptor. Use
536 * <code>null</code> to act as a default acceptor principal.
537 * @return an unestablished GSSContext
538 *
539 * @see GSSContext
540 *
541 * @throws GSSException containing the following
542 * major error codes:
543 * {@link GSSException#NO_CRED GSSException.NO_CRED}
544 * {@link GSSException#CREDENTIALS_EXPIRED
545 * GSSException.CREDENTIALS_EXPIRED}
546 * {@link GSSException#BAD_MECH GSSException.BAD_MECH}
547 * {@link GSSException#FAILURE GSSException.FAILURE}
548 */
549 public abstract GSSContext createContext(GSSCredential myCred)
550 throws GSSException;
551
552 /**
553 * Factory method for creating a previously exported context. The
554 * context properties will be determined from the input token and
555 * cannot be modified through the set methods.<p>
556 *
557 * Implementations are not required to support the inter-process
558 * transfer of security contexts. Before exporting a context, calling
559 * the {@link GSSContext#isTransferable() GSSContext.isTransferable}
560 * will indicate if the context is transferable. Calling this method in
561 * an implementation that does not support it will result in a
562 * <code>GSSException</code> with the error
563 * code {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE}.
564 *
565 * Some mechanism providers might require that the caller be granted
566 * permission to initiate or accept a security context. A failed
567 * permission check might cause a {@link java.lang.SecurityException
568 * SecurityException} to be thrown from this method.
569 *
570 * @param interProcessToken the token previously emitted from the
571 * export method.
572 * @return the previously established GSSContext
573 *
574 * @see GSSContext
575 *
576 * @throws GSSException containing the following
577 * major error codes:
578 * {@link GSSException#NO_CONTEXT GSSException.NO_CONTEXT},
579 * {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
580 * {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE},
581 * {@link GSSException#UNAUTHORIZED GSSException.UNAUTHORIZED},
582 * {@link GSSException#FAILURE GSSException.FAILURE}
583 */
584 public abstract GSSContext createContext(byte [] interProcessToken)
585 throws GSSException;
586
587 /**
588 * This method is used to indicate to the GSSManager that the
589 * application would like a particular provider to be used ahead of all
590 * others when support is desired for the given mechanism. When a value
591 * of null is used instead of an <code>Oid</code> for the mechanism,
592 * the GSSManager must use the indicated provider ahead of all others
593 * no matter what the mechanism is. Only when the indicated provider
594 * does not support the needed mechanism should the GSSManager move on
595 * to a different provider.<p>
596 *
597 * Calling this method repeatedly preserves the older settings but
598 * lowers them in preference thus forming an ordered list of provider
599 * and <code>Oid</code> pairs that grows at the top.<p>
600 *
601 * Calling addProviderAtFront with a null <code>Oid</code> will remove
602 * all previous preferences that were set for this provider in the
603 * GSSManager instance. Calling addProviderAtFront with a non-null
604 * <code>Oid</code> will remove any previous preference that was set
605 * using this mechanism and this provider together.<p>
606 *
607 * If the GSSManager implementation does not support an SPI with a
608 * pluggable provider architecture it should throw a GSSException with
609 * the status code GSSException.UNAVAILABLE to indicate that the
610 * operation is unavailable.<p>
611 *
612 * Suppose an application desired that the provider A always be checked
613 * first when any mechanism is needed, it would call:<p>
614 * <pre>
615 * GSSManager mgr = GSSManager.getInstance();
616 * // mgr may at this point have its own pre-configured list
617 * // of provider preferences. The following will prepend to
618 * // any such list:
619 *
620 * mgr.addProviderAtFront(A, null);
621 * </pre>
622 * Now if it also desired that the mechanism of Oid m1 always be
623 * obtained from the provider B before the previously set A was checked,
624 * it would call:<p>
625 * <pre>
626 * mgr.addProviderAtFront(B, m1);
627 * </pre>
628 * The GSSManager would then first check with B if m1 was needed. In
629 * case B did not provide support for m1, the GSSManager would continue
630 * on to check with A. If any mechanism m2 is needed where m2 is
631 * different from m1 then the GSSManager would skip B and check with A
632 * directly.<p>
633 *
634 * Suppose at a later time the following call is made to the same
635 * GSSManager instance:<p>
636 * <pre>
637 * mgr.addProviderAtFront(B, null)
638 * </pre>
639 * then the previous setting with the pair (B, m1) is subsumed by this
640 * and should be removed. Effectively the list of preferences now
641 * becomes {(B, null), (A, null),
642 * ... //followed by the pre-configured list.<p>
643 *
644 * Please note, however, that the following call:
645 * <pre>
646 * mgr.addProviderAtFront(A, m3)
647 * </pre>
648 * does not subsume the previous setting of (A, null) and the list will
649 * effectively become {(A, m3), (B, null), (A, null), ...}
650 *
651 * @param p the provider instance that should be used whenever support
652 * is needed for mech.
653 * @param mech the mechanism for which the provider is being set
654 *
655 * @throws GSSException containing the following
656 * major error codes:
657 * {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE},
658 * {@link GSSException#FAILURE GSSException.FAILURE}
659 */
660 public abstract void addProviderAtFront(Provider p, Oid mech)
661 throws GSSException;
662
663 /**
664 * This method is used to indicate to the GSSManager that the
665 * application would like a particular provider to be used if no other
666 * provider can be found that supports the given mechanism. When a value
667 * of null is used instead of an Oid for the mechanism, the GSSManager
668 * must use the indicated provider for any mechanism.<p>
669 *
670 * Calling this method repeatedly preserves the older settings but
671 * raises them above newer ones in preference thus forming an ordered
672 * list of providers and Oid pairs that grows at the bottom. Thus the
673 * older provider settings will be utilized first before this one is.<p>
674 *
675 * If there are any previously existing preferences that conflict with
676 * the preference being set here, then the GSSManager should ignore this
677 * request.<p>
678 *
679 * If the GSSManager implementation does not support an SPI with a
680 * pluggable provider architecture it should throw a GSSException with
681 * the status code GSSException.UNAVAILABLE to indicate that the
682 * operation is unavailable.<p>
683 *
684 * Suppose an application desired that when a mechanism of Oid m1 is
685 * needed the system default providers always be checked first, and only
686 * when they do not support m1 should a provider A be checked. It would
687 * then make the call:<p>
688 * <pre>
689 * GSSManager mgr = GSSManager.getInstance();
690 * mgr.addProviderAtEnd(A, m1);
691 * </pre>
692 * Now, if it also desired that for all mechanisms the provider B be
693 * checked after all configured providers have been checked, it would
694 * then call:<p>
695 * <pre>
696 * mgr.addProviderAtEnd(B, null);
697 * </pre>
698 * Effectively the list of preferences now becomes {..., (A, m1), (B,
699 * null)}.<p>
700 *
701 * Suppose at a later time the following call is made to the same
702 * GSSManager instance:<p>
703 * <pre>
704 * mgr.addProviderAtEnd(B, m2)
705 * </pre>
706 * then the previous setting with the pair (B, null) subsumes this and
707 * therefore this request should be ignored. The same would happen if a
708 * request is made for the already existing pairs of (A, m1) or (B,
709 * null).<p>
710 *
711 * Please note, however, that the following call:<p>
712 * <pre>
713 * mgr.addProviderAtEnd(A, null)
714 * </pre>
715 * is not subsumed by the previous setting of (A, m1) and the list will
716 * effectively become {..., (A, m1), (B, null), (A, null)}
717 *
718 * @param p the provider instance that should be used whenever support
719 * is needed for mech.
720 * @param mech the mechanism for which the provider is being set
721 *
722 * @throws GSSException containing the following
723 * major error codes:
724 * {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE},
725 * {@link GSSException#FAILURE GSSException.FAILURE}
726 */
727 public abstract void addProviderAtEnd(Provider p, Oid mech)
728 throws GSSException;
729 }