| Frames | No Frames |
1: /* GSSName.java -- a name interface for GSS. 2: Copyright (C) 2004 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. 37: 38: The documentation comments of this class are derived from the text 39: of RFC 2853: Generic Security Service API Version 2: Java Bindings. 40: That document is covered under the following license notice: 41: 42: Copyright (C) The Internet Society (2000). All Rights Reserved. 43: 44: This document and translations of it may be copied and furnished to 45: others, and derivative works that comment on or otherwise explain it 46: or assist in its implementation may be prepared, copied, published and 47: distributed, in whole or in part, without restriction of any kind, 48: provided that the above copyright notice and this paragraph are 49: included on all such copies and derivative works. However, this 50: document itself may not be modified in any way, such as by removing 51: the copyright notice or references to the Internet Society or other 52: Internet organizations, except as needed for the purpose of developing 53: Internet standards in which case the procedures for copyrights defined 54: in the Internet Standards process must be followed, or as required to 55: translate it into languages other than English. 56: 57: The limited permissions granted above are perpetual and will not be 58: revoked by the Internet Society or its successors or assigns. 59: 60: This document and the information contained herein is provided on an 61: "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 62: TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT 63: NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN 64: WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 65: MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. */ 66: 67: 68: package org.ietf.jgss; 69: 70: /** 71: * <p>This interface encapsulates a single GSS-API principal entity. 72: * Different name formats and their definitions are identified with 73: * universal Object Identifiers (Oids). The format of the names can be 74: * derived based on the unique oid of its namespace type.</p> 75: * 76: * <h3>Example Code</h3> 77: * 78: * <pre> 79: GSSManager mgr = GSSManager.getInstance(); 80: 81: // create a host based service name 82: GSSName name = mgr.createName("service@host", 83: GSSName.NT_HOSTBASED_SERVICE); 84: 85: Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 86: 87: GSSName mechName = name.canonicalize(krb5); 88: 89: // the above two steps are equivalent to the following 90: GSSName mechName = mgr.createName("service@host", 91: GSSName.NT_HOSTBASED_SERVICE, krb5); 92: 93: // perform name comparison 94: if (name.equals(mechName)) 95: print("Names are equal."); 96: 97: // obtain textual representation of name and its printable 98: // name type 99: print(mechName.toString() + 100: mechName.getStringNameType().toString()); 101: 102: // export and re-import the name 103: byte [] exportName = mechName.export(); 104: 105: // create a new name object from the exported buffer 106: GSSName newName = mgr.createName(exportName, 107: GSSName.NT_EXPORT_NAME); 108: </pre> 109: */ 110: public interface GSSName 111: { 112: 113: // Constants. 114: // ------------------------------------------------------------------------- 115: 116: /** 117: * <p>Name type for representing an anonymous entity. It represents the 118: * following value: <code>{ 1(iso), 3(org), 6(dod), 1(internet), 5(security), 119: * 6(nametypes), 3(gss-anonymous-name) }</code>.</p> 120: */ 121: Oid NT_ANONYMOUS = new Oid(new int[] { 1, 3, 6, 1, 5, 6, 3 }); 122: 123: /** 124: * <p>Name type used to indicate an exported name produced by the export 125: * method. It represents the following value: <code>{ 1(iso), 3(org), 6(dod), 126: * 1(internet), 5(security), 6(nametypes), 4(gss-api-exported-name) 127: * }</code>.</p> 128: */ 129: Oid NT_EXPORT_NAME = new Oid(new int[] { 1, 3, 6, 1, 5, 6, 4 }); 130: 131: /** 132: * <p>Oid indicating a host-based service name form. It is used to 133: * represent services associated with host computers. This name form is 134: * constructed using two elements, "service" and "hostname", as follows:</p> 135: * 136: * <blockquote><code>service@hostname</code></blockquote> 137: * 138: * <p>Values for the "service" element are registered with the IANA. It 139: * represents the following value: <code>{ 1(iso), 3(org), 6(dod), 140: * 1(internet), 5(security), 6(nametypes), 2(gss-host-based-services) 141: * }</code>.</p> 142: */ 143: Oid NT_HOSTBASED_SERVICE = new Oid(new int[] { 1, 3, 6, 1, 5, 6, 2 }); 144: 145: /** 146: * <p>Name type to indicate a numeric user identifier corresponding to a 147: * user on a local system. (e.g. Uid). It represents the following 148: * value: <code>{ iso(1) member-body(2) United States(840) mit(113554) 149: * infosys(1) gssapi(2) generic(1) machine_uid_name(2) }</code>.</p> 150: */ 151: Oid NT_MACHINE_UID_NAME = new Oid(new int[] { 1, 2, 840, 113554, 1, 2, 1, 2 }); 152: 153: /** 154: * <p>Name type to indicate a string of digits representing the numeric 155: * user identifier of a user on a local system. It represents the 156: * following value: <code>{ iso(1) member-body(2) United States(840) 157: * mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) 158: * }</code>.</p> 159: */ 160: Oid NT_STRING_UID_NAME = new Oid(new int[] { 1, 2, 840, 113554, 1, 2, 1, 3 }); 161: 162: /** 163: * <p>Name type to indicate a named user on a local system. It represents 164: * the following value: <code>{ iso(1) member-body(2) United States(840) 165: * mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) }</code>.</p> 166: */ 167: Oid NT_USER_NAME = new Oid(new int[] { 1, 2, 840, 113554, 1, 2, 1, 1 }); 168: 169: // Instance methods. 170: // ------------------------------------------------------------------------- 171: 172: /** 173: * Compares two GSSName objects to determine whether they refer to the 174: * same entity. This method may throw a {@link GSSException} when the 175: * names cannot be compared. If either of the names represents an 176: * anonymous entity, the method will return <code>false</code>. 177: * 178: * @param another GSSName object to compare with. 179: * @return True if this name equals the other, and if neither name 180: * represents an anonymous entity. 181: * @throws GSSException If the names cannot be compared. 182: */ 183: boolean equals(GSSName another) throws GSSException; 184: 185: /** 186: * A variation of the {@link #equals(org.ietf.jgss.GSSName)} method that 187: * is provided to override the {@link Object#equals(java.lang.Object)} 188: * method that the implementing class will inherit. The behavior is 189: * exactly the same as that in the other equals method except that no 190: * {@link GSSException} is thrown; instead, <code>false</code> will be 191: * returned in the situation where an error occurs. (Note that the Java 192: * language specification requires that two objects that are equal 193: * according to the {@link Object#equals(java.lang.Object)} method must 194: * return the same integer when the {@link hashCode()} method is called 195: * on them. 196: * 197: * @param another GSSName object to compare with. 198: * @return True if this name equals the other, if neither name 199: * represents an anonymous entity, or if an error occurs. 200: */ 201: boolean equals(Object another); 202: 203: /** 204: * Return the hashcode of this GSSName. When overriding {@link #equals}, 205: * it is normally necessary to override hashCode() as well. 206: * 207: * @return the hash code that must be the same for two names if {@link #equals} 208: * returns true. 209: */ 210: int hashCode(); 211: 212: /** 213: * Creates a mechanism name (MN) from an arbitrary internal name. This 214: * is equivalent to using the factory methods {@link 215: * GSSManager#createName(java.lang.String,org.ietf.jgss.Oid,org.ietf.jgss.Oid)} 216: * or {@link 217: * GSSManager#createName(byte[],org.ietf.jgss.Oid,org.ietf.jgss.Oid)}. 218: * 219: * @param mech The oid for the mechanism for which the canonical form 220: * of the name is requested. 221: * @return The mechanism name. 222: * @throws GSSException If this operation fails. 223: */ 224: GSSName canonicalize(Oid mech) throws GSSException; 225: 226: /** 227: * Returns a canonical contiguous byte representation of a mechanism 228: * name (MN), suitable for direct, byte by byte comparison by 229: * authorization functions. If the name is not an MN, implementations 230: * may throw a {@link GSSException} with the {@link GSSException#NAME_NOT_MN} 231: * status code. If an implementation chooses not to throw an exception, 232: * it should use some system specific default mechanism to canonicalize 233: * the name and then export it. The format of the header of the output 234: * buffer is specified in <a 235: * href="http://www.ietf.org/rfc/rfc2743.txt">RFC 2743</a>. 236: * 237: * @return The exported name. 238: * @throws GSSException If the name is not an MN and the implementation 239: * throws an exception for this case. 240: */ 241: byte[] export() throws GSSException; 242: 243: /** 244: * Returns a textual representation of the GSSName object. To retrieve 245: * the printed name format, which determines the syntax of the returned 246: * string, the {@link #getStringNameType()} method can be used. 247: * 248: * @return The textual representation of the GSSName object. 249: */ 250: String toString(); 251: 252: /** 253: * Returns the oid representing the type of name returned through the 254: * {@link #toString()} method. Using this oid, the syntax of the printable 255: * name can be determined. 256: * 257: * @return The name type. 258: * @throws GSSException If this operation fails. 259: */ 260: Oid getStringNameType() throws GSSException; 261: 262: /** 263: * Tests if this name object represents an anonymous entity. Returns 264: * <code>true</code> if this is an anonymous name. 265: * 266: * @return True if this name represents an anonymous entity. 267: */ 268: boolean isAnonymous(); 269: 270: /** 271: * Tests if this name object contains only one mechanism element and is 272: * thus a mechanism name as defined by <a 273: * href="http://www.ietf.org/rfc/rfc2743.txt">RFC 2743</a>. 274: * 275: * @return True if this name is a mechanism name. 276: */ 277: boolean isMN(); 278: }