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