Source for org.ietf.jgss.GSSName

   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: }