GSSManager


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