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