GSSName


1   /*
2    * @(#)GSSName.java 1.7 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package org.ietf.jgss;
9   
10  import sun.security.jgss.spi.*;
11  import java.util.Vector  ;
12  import java.util.Enumeration  ;
13  
14  /**  
15   * This interface encapsulates a single GSS-API principal entity. The
16   * application obtains an implementation of this interface 
17   * through one of the <code>createName</code> methods that exist in the {@link
18   * GSSManager GSSManager} class. Conceptually a GSSName contains many
19   * representations of the entity or many primitive name elements, one for
20   * each supported underlying mechanism. In GSS terminology, a GSSName that
21   * contains an element from just one mechanism is called a Mechanism Name
22   * (MN)<p>
23   * 
24   * Since different authentication mechanisms may employ different
25   * namespaces for identifying their principals, GSS-API's naming support is
26   * necessarily complex in multi-mechanism environments (or even in some
27   * single-mechanism environments where the underlying mechanism supports
28   * multiple namespaces). Different name formats and their definitions are
29   * identified with {@link Oid Oid's} and some standard types
30   * are defind in this interface. The format of the names can be derived
31   * based on the unique <code>Oid</code> of its name type.<p>
32   *
33   * Included below are code examples utilizing the <code>GSSName</code> interface.
34   * The code below creates a <code>GSSName</code>, converts it to an MN, performs a
35   * comparison, obtains a printable representation of the name, exports it
36   * to a byte array and then re-imports to obtain a
37   * new <code>GSSName</code>.<p>
38   * <pre>
39   *      GSSManager manager = GSSManager.getInstance();
40   *
41   *      // create a host based service name
42   *      GSSName name = manager.createName("service@host",
43   *                   GSSName.NT_HOSTBASED_SERVICE);
44   *
45   *      Oid krb5 = new Oid("1.2.840.113554.1.2.2");
46   *
47   *      GSSName mechName = name.canonicalize(krb5);
48   *   
49   *      // the above two steps are equivalent to the following
50   *      GSSName mechName = manager.createName("service@host",
51   *                      GSSName.NT_HOSTBASED_SERVICE, krb5);
52   *   
53   *      // perform name comparison
54   *      if (name.equals(mechName))
55   *              print("Names are equals.");
56   *   
57   *      // obtain textual representation of name and its printable
58   *      // name type
59   *      print(mechName.toString() +
60   *                      mechName.getStringNameType().toString());
61   *   
62   *      // export and re-import the name
63   *      byte [] exportName = mechName.export();
64   *   
65   *      // create a new name object from the exported buffer
66   *      GSSName newName = manager.createName(exportName,
67   *                      GSSName.NT_EXPORT_NAME);
68   *   
69   * </pre>
70   * @see #export()
71   * @see #equals(GSSName)
72   * @see GSSManager#createName(String, Oid)
73   * @see GSSManager#createName(String, Oid, Oid)
74   * @see GSSManager#createName(byte[], Oid)
75   *
76   * @author Mayank Upadhyay
77   * @version 1.7, 12/19/03
78   * @since 1.4
79   */
80  public interface GSSName {
81      
82      /**
83       * Oid indicating a host-based service name form.  It is used to
84       * represent services associated with host computers.  This name form
85       * is constructed using two elements, "service" and "hostname", as
86       * follows: service@hostname.<p>
87       *
88       * It represents the following Oid value:<br>
89       * <code>{ 1(iso), 3(org), 6(dod), 1(internet), 5(security),
90       * 6(nametypes), 2(gss-host-based-services) }</code>
91       */
92      public static final Oid   NT_HOSTBASED_SERVICE 
93      = Oid.getInstance("1.3.6.1.5.6.2");
94      
95      /**    
96       * Name type to indicate a named user on a local system.<p>
97       * It represents the following Oid value:<br>
98       *  <code>{ iso(1) member-body(2) United
99       * States(840) mit(113554) infosys(1) gssapi(2) generic(1) user_name(1)
100      * }</code>
101      */
102     public static final Oid   NT_USER_NAME 
103     = Oid.getInstance("1.2.840.113554.1.2.1.1");
104 
105     /**
106      * Name type to indicate a numeric user identifier corresponding to a
107      * user on a local system. (e.g. Uid).<p>
108      *
109      *  It represents the following Oid value:<br>
110      * <code>{ iso(1) member-body(2) United States(840) mit(113554)
111      * infosys(1) gssapi(2) generic(1) machine_uid_name(2) }</code>
112      */
113     public static final Oid   NT_MACHINE_UID_NAME 
114     = Oid.getInstance("1.2.840.113554.1.2.1.2");
115 
116     /**
117      * Name type to indicate a string of digits representing the numeric
118      * user identifier of a user on a local system.<p>
119      *
120      * It represents the following Oid value:<br>
121      * <code>{ iso(1) member-body(2) United
122      * States(840) mit(113554) infosys(1) gssapi(2) generic(1)
123      * string_uid_name(3) }</code>
124      */
125     public static final Oid   NT_STRING_UID_NAME 
126     = Oid.getInstance("1.2.840.113554.1.2.1.3");
127 
128     /**    
129      * Name type for representing an anonymous entity.<p>
130      * It represents the following Oid value:<br>
131      * <code>{ 1(iso), 3(org), 6(dod), 1(internet),
132      * 5(security), 6(nametypes), 3(gss-anonymous-name) }</code>
133      */
134     public static final Oid   NT_ANONYMOUS 
135     = Oid.getInstance("1.3.6.1.5.6.3");
136 
137     /** 
138      * Name type used to indicate an exported name produced by the export
139      * method.<p>
140      *
141      * It represents the following Oid value:<br> <code>{ 1(iso),
142      * 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
143      * 4(gss-api-exported-name) }</code>
144      */
145     public static final Oid   NT_EXPORT_NAME 
146     = Oid.getInstance("1.3.6.1.5.6.4");
147     
148     /**    
149      * Compares two <code>GSSName</code> objects to determine if they refer to the
150      * same entity.
151      * 
152      * @param another the <code>GSSName</code> to compare this name with
153      * @return true if the two names contain at least one primitive element
154      * in common. If either of the names represents an anonymous entity, the
155      * method will return false.
156      *
157      * @throws GSSException when the names cannot be compared, containing the following
158      * major error codes: 
159      *         {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
160      *         {@link GSSException#FAILURE GSSException.FAILURE}
161      */
162     public boolean equals(GSSName   another) throws GSSException  ;
163     
164     /**    
165      * Compares this <code>GSSName</code> object to another Object that might be a
166      * <code>GSSName</code>. The behaviour is exactly the same as in {@link
167      * #equals(GSSName) equals} except that no GSSException is thrown;
168      * instead, false will be returned in the situation where an error
169      * occurs.
170      * @return true if the object to compare to is also a <code>GSSName</code> and the two 
171      * names refer to the same entity.
172      * @param another the object to compare this name to
173      * @see #equals(GSSName)
174      */
175     public boolean equals(Object   another);
176     
177     /**
178      * Returns a hashcode value for this GSSName.
179      *
180      * @return a hashCode value
181      */
182     public int hashCode();
183 
184     /**   
185      * Creates a name that is canonicalized for some
186      * mechanism.
187      *
188      * @return a <code>GSSName</code> that contains just one primitive
189      * element representing this name in a canonicalized form for the desired
190      * mechanism.
191      * @param mech the oid for the mechanism for which the canonical form of
192      * the name is requested.
193      *
194      * @throws GSSException containing the following 
195      * major error codes: 
196      *         {@link GSSException#BAD_MECH GSSException.BAD_MECH},
197      *         {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
198      *         {@link GSSException#BAD_NAME GSSException.BAD_NAME},
199      *         {@link GSSException#FAILURE GSSException.FAILURE}
200      */
201     public GSSName   canonicalize(Oid   mech) throws GSSException  ;
202     
203     /**    
204      * Returns a canonical contiguous byte representation of a mechanism name 
205      * (MN), suitable for direct, byte by byte comparison by authorization
206      * functions.  If the name is not an MN, implementations may throw a
207      * GSSException with the NAME_NOT_MN status code.  If an implementation
208      * chooses not to throw an exception, it should use some system specific
209      * default mechanism to canonicalize the name and then export
210      * it. Structurally, an exported name object consists of a header
211      * containing an OID identifying the mechanism that authenticated the
212      * name, and a trailer containing the name itself, where the syntax of
213      * the trailer is defined by the individual mechanism specification. The
214      * format of the header of the output buffer is specified in RFC 2743.<p> 
215      *
216      * The exported name is useful when used in large access control lists
217      * where the overhead of creating a <code>GSSName</code> object on each
218      * name and invoking the equals method on each name from the ACL may be
219      * prohibitive.<p>
220      *
221      * Exported names may be re-imported by using the byte array factory
222      * method {@link GSSManager#createName(byte[], Oid)
223      * GSSManager.createName} and specifying the NT_EXPORT_NAME as the name
224      * type object identifier. The resulting <code>GSSName</code> name will
225      * also be a MN.<p>  
226      * @return a byte[] containing the exported name. RFC 2743 defines the
227      * "Mechanism-Independent Exported Name Object Format" for these bytes.
228      *
229      * @throws GSSException containing the following 
230      * major error codes: 
231      *         {@link GSSException#BAD_NAME GSSException.BAD_NAME},
232      *         {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
233      *         {@link GSSException#FAILURE GSSException.FAILURE}
234      */
235     public byte[] export() throws GSSException  ;
236     
237     /**    
238      * Returns a textual representation of the <code>GSSName</code> object.  To retrieve
239      * the printed name format, which determines the syntax of the returned
240      * string, use the {@link #getStringNameType() getStringNameType}
241      * method.
242      *
243      * @return a String representing this name in printable form.
244      */
245     public String   toString();
246     
247     /**    
248      * Returns the name type of the printable
249      * representation of this name that can be obtained from the <code>
250      * toString</code> method.
251      *
252      * @return an Oid representing the namespace of the name returned
253      * from the toString method.
254      *
255      * @throws GSSException containing the following 
256      * major error codes: 
257      *         {@link GSSException#FAILURE GSSException.FAILURE}
258      */
259     public Oid   getStringNameType() throws GSSException  ;
260     
261     /** 
262      * Tests if this name object represents an anonymous entity.
263      *
264      * @return true if this is an anonymous name, false otherwise.
265      */
266     public boolean isAnonymous();
267     
268     /** 
269      * Tests if this name object represents a Mechanism Name (MN). An MN is 
270      * a GSSName the contains exactly one mechanism's primitive name
271      * element.
272      *
273      * @return true if this is an MN, false otherwise.
274      */
275     public boolean isMN();
276     
277 }
278
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags