J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 2000 Sun Microsystems, Inc. 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. 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> |
| 106 | * <code>{ 1(iso), 3(org), 6(dod), 1(internet), 5(security), |
| 107 | * 6(nametypes), 2(gss-host-based-services) }</code> |
| 108 | */ |
| 109 | public static final Oid NT_HOSTBASED_SERVICE |
| 110 | = Oid.getInstance("1.3.6.1.5.6.2"); |
| 111 | |
| 112 | /** |
| 113 | * Name type to indicate a named user on a local system.<p> |
| 114 | * It represents the following Oid value:<br> |
| 115 | * <code>{ iso(1) member-body(2) United |
| 116 | * States(840) mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) |
| 117 | * }</code> |
| 118 | */ |
| 119 | public static final Oid NT_USER_NAME |
| 120 | = Oid.getInstance("1.2.840.113554.1.2.1.1"); |
| 121 | |
| 122 | /** |
| 123 | * Name type to indicate a numeric user identifier corresponding to a |
| 124 | * user on a local system. (e.g. Uid).<p> |
| 125 | * |
| 126 | * It represents the following Oid value:<br> |
| 127 | * <code>{ iso(1) member-body(2) United States(840) mit(113554) |
| 128 | * infosys(1) gssapi(2) generic(1) machine_uid_name(2) }</code> |
| 129 | */ |
| 130 | public static final Oid NT_MACHINE_UID_NAME |
| 131 | = Oid.getInstance("1.2.840.113554.1.2.1.2"); |
| 132 | |
| 133 | /** |
| 134 | * Name type to indicate a string of digits representing the numeric |
| 135 | * user identifier of a user on a local system.<p> |
| 136 | * |
| 137 | * It represents the following Oid value:<br> |
| 138 | * <code>{ iso(1) member-body(2) United |
| 139 | * States(840) mit(113554) infosys(1) gssapi(2) generic(1) |
| 140 | * string_uid_name(3) }</code> |
| 141 | */ |
| 142 | public static final Oid NT_STRING_UID_NAME |
| 143 | = Oid.getInstance("1.2.840.113554.1.2.1.3"); |
| 144 | |
| 145 | /** |
| 146 | * Name type for representing an anonymous entity.<p> |
| 147 | * It represents the following Oid value:<br> |
| 148 | * <code>{ 1(iso), 3(org), 6(dod), 1(internet), |
| 149 | * 5(security), 6(nametypes), 3(gss-anonymous-name) }</code> |
| 150 | */ |
| 151 | public static final Oid NT_ANONYMOUS |
| 152 | = Oid.getInstance("1.3.6.1.5.6.3"); |
| 153 | |
| 154 | /** |
| 155 | * Name type used to indicate an exported name produced by the export |
| 156 | * method.<p> |
| 157 | * |
| 158 | * It represents the following Oid value:<br> <code>{ 1(iso), |
| 159 | * 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), |
| 160 | * 4(gss-api-exported-name) }</code> |
| 161 | */ |
| 162 | public static final Oid NT_EXPORT_NAME |
| 163 | = Oid.getInstance("1.3.6.1.5.6.4"); |
| 164 | |
| 165 | /** |
| 166 | * Compares two <code>GSSName</code> objects to determine if they refer to the |
| 167 | * same entity. |
| 168 | * |
| 169 | * @param another the <code>GSSName</code> to compare this name with |
| 170 | * @return true if the two names contain at least one primitive element |
| 171 | * in common. If either of the names represents an anonymous entity, the |
| 172 | * method will return false. |
| 173 | * |
| 174 | * @throws GSSException when the names cannot be compared, containing the following |
| 175 | * major error codes: |
| 176 | * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE}, |
| 177 | * {@link GSSException#FAILURE GSSException.FAILURE} |
| 178 | */ |
| 179 | public boolean equals(GSSName another) throws GSSException; |
| 180 | |
| 181 | /** |
| 182 | * Compares this <code>GSSName</code> object to another Object that might be a |
| 183 | * <code>GSSName</code>. The behaviour is exactly the same as in {@link |
| 184 | * #equals(GSSName) equals} except that no GSSException is thrown; |
| 185 | * instead, false will be returned in the situation where an error |
| 186 | * occurs. |
| 187 | * @return true if the object to compare to is also a <code>GSSName</code> and the two |
| 188 | * names refer to the same entity. |
| 189 | * @param another the object to compare this name to |
| 190 | * @see #equals(GSSName) |
| 191 | */ |
| 192 | public boolean equals(Object another); |
| 193 | |
| 194 | /** |
| 195 | * Returns a hashcode value for this GSSName. |
| 196 | * |
| 197 | * @return a hashCode value |
| 198 | */ |
| 199 | public int hashCode(); |
| 200 | |
| 201 | /** |
| 202 | * Creates a name that is canonicalized for some |
| 203 | * mechanism. |
| 204 | * |
| 205 | * @return a <code>GSSName</code> that contains just one primitive |
| 206 | * element representing this name in a canonicalized form for the desired |
| 207 | * mechanism. |
| 208 | * @param mech the oid for the mechanism for which the canonical form of |
| 209 | * the name is requested. |
| 210 | * |
| 211 | * @throws GSSException containing the following |
| 212 | * major error codes: |
| 213 | * {@link GSSException#BAD_MECH GSSException.BAD_MECH}, |
| 214 | * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE}, |
| 215 | * {@link GSSException#BAD_NAME GSSException.BAD_NAME}, |
| 216 | * {@link GSSException#FAILURE GSSException.FAILURE} |
| 217 | */ |
| 218 | public GSSName canonicalize(Oid mech) throws GSSException; |
| 219 | |
| 220 | /** |
| 221 | * Returns a canonical contiguous byte representation of a mechanism name |
| 222 | * (MN), suitable for direct, byte by byte comparison by authorization |
| 223 | * functions. If the name is not an MN, implementations may throw a |
| 224 | * GSSException with the NAME_NOT_MN status code. If an implementation |
| 225 | * chooses not to throw an exception, it should use some system specific |
| 226 | * default mechanism to canonicalize the name and then export |
| 227 | * it. Structurally, an exported name object consists of a header |
| 228 | * containing an OID identifying the mechanism that authenticated the |
| 229 | * name, and a trailer containing the name itself, where the syntax of |
| 230 | * the trailer is defined by the individual mechanism specification. The |
| 231 | * format of the header of the output buffer is specified in RFC 2743.<p> |
| 232 | * |
| 233 | * The exported name is useful when used in large access control lists |
| 234 | * where the overhead of creating a <code>GSSName</code> object on each |
| 235 | * name and invoking the equals method on each name from the ACL may be |
| 236 | * prohibitive.<p> |
| 237 | * |
| 238 | * Exported names may be re-imported by using the byte array factory |
| 239 | * method {@link GSSManager#createName(byte[], Oid) |
| 240 | * GSSManager.createName} and specifying the NT_EXPORT_NAME as the name |
| 241 | * type object identifier. The resulting <code>GSSName</code> name will |
| 242 | * also be a MN.<p> |
| 243 | * @return a byte[] containing the exported name. RFC 2743 defines the |
| 244 | * "Mechanism-Independent Exported Name Object Format" for these bytes. |
| 245 | * |
| 246 | * @throws GSSException containing the following |
| 247 | * major error codes: |
| 248 | * {@link GSSException#BAD_NAME GSSException.BAD_NAME}, |
| 249 | * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE}, |
| 250 | * {@link GSSException#FAILURE GSSException.FAILURE} |
| 251 | */ |
| 252 | public byte[] export() throws GSSException; |
| 253 | |
| 254 | /** |
| 255 | * Returns a textual representation of the <code>GSSName</code> object. To retrieve |
| 256 | * the printed name format, which determines the syntax of the returned |
| 257 | * string, use the {@link #getStringNameType() getStringNameType} |
| 258 | * method. |
| 259 | * |
| 260 | * @return a String representing this name in printable form. |
| 261 | */ |
| 262 | public String toString(); |
| 263 | |
| 264 | /** |
| 265 | * Returns the name type of the printable |
| 266 | * representation of this name that can be obtained from the <code> |
| 267 | * toString</code> method. |
| 268 | * |
| 269 | * @return an Oid representing the namespace of the name returned |
| 270 | * from the toString method. |
| 271 | * |
| 272 | * @throws GSSException containing the following |
| 273 | * major error codes: |
| 274 | * {@link GSSException#FAILURE GSSException.FAILURE} |
| 275 | */ |
| 276 | public Oid getStringNameType() throws GSSException; |
| 277 | |
| 278 | /** |
| 279 | * Tests if this name object represents an anonymous entity. |
| 280 | * |
| 281 | * @return true if this is an anonymous name, false otherwise. |
| 282 | */ |
| 283 | public boolean isAnonymous(); |
| 284 | |
| 285 | /** |
| 286 | * Tests if this name object represents a Mechanism Name (MN). An MN is |
| 287 | * a GSSName the contains exactly one mechanism's primitive name |
| 288 | * element. |
| 289 | * |
| 290 | * @return true if this is an MN, false otherwise. |
| 291 | */ |
| 292 | public boolean isMN(); |
| 293 | |
| 294 | } |