org.ietf.jgss
Interface GSSName


public interface GSSName

This interface encapsulates a single GSS-API principal entity. The application obtains an implementation of this interface through one of the createName methods that exist in the GSSManager sample code for org.ietf.jgss.GSSManager definition code for org.ietf.jgss.GSSManager class. Conceptually a GSSName contains many representations of the entity or many primitive name elements, one for each supported underlying mechanism. In GSS terminology, a GSSName that contains an element from just one mechanism is called a Mechanism Name (MN)

Since different authentication mechanisms may employ different namespaces for identifying their principals, GSS-API's naming support is necessarily complex in multi-mechanism environments (or even in some single-mechanism environments where the underlying mechanism supports multiple namespaces). Different name formats and their definitions are identified with Oid's sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid and some standard types are defind in this interface. The format of the names can be derived based on the unique Oid of its name type.

Included below are code examples utilizing the GSSName interface. The code below creates a GSSName, converts it to an MN, performs a comparison, obtains a printable representation of the name, exports it to a byte array and then re-imports to obtain a new GSSName.

      GSSManager manager = GSSManager.getInstance();

      // create a host based service name
      GSSName name = manager.createName("service@host",
                   GSSName.NT_HOSTBASED_SERVICE);

      Oid krb5 = new Oid("1.2.840.113554.1.2.2");

      GSSName mechName = name.canonicalize(krb5);
   
      // the above two steps are equivalent to the following
      GSSName mechName = manager.createName("service@host",
                      GSSName.NT_HOSTBASED_SERVICE, krb5);
   
      // perform name comparison
      if (name.equals(mechName))
              print("Names are equals.");
   
      // obtain textual representation of name and its printable
      // name type
      print(mechName.toString() +
                      mechName.getStringNameType().toString());
   
      // export and re-import the name
      byte [] exportName = mechName.export();
   
      // create a new name object from the exported buffer
      GSSName newName = manager.createName(exportName,
                      GSSName.NT_EXPORT_NAME);
   
 

Since:
1.4
See Also:
export() sample code for org.ietf.jgss.GSSName.export() definition code for org.ietf.jgss.GSSName.export() , equals(GSSName) sample code for org.ietf.jgss.GSSName.equals(org.ietf.jgss.GSSName) definition code for org.ietf.jgss.GSSName.equals(org.ietf.jgss.GSSName) , GSSManager.createName(String, Oid) sample code for org.ietf.jgss.GSSManager.createName(java.lang.String, org.ietf.jgss.Oid) definition code for org.ietf.jgss.GSSManager.createName(java.lang.String, org.ietf.jgss.Oid) , GSSManager.createName(String, Oid, Oid) sample code for org.ietf.jgss.GSSManager.createName(java.lang.String, org.ietf.jgss.Oid, org.ietf.jgss.Oid) definition code for org.ietf.jgss.GSSManager.createName(java.lang.String, org.ietf.jgss.Oid, org.ietf.jgss.Oid) , GSSManager.createName(byte[], Oid) sample code for org.ietf.jgss.GSSManager.createName(byte[], org.ietf.jgss.Oid) definition code for org.ietf.jgss.GSSManager.createName(byte[], org.ietf.jgss.Oid)

Field Summary
static Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid NT_ANONYMOUS sample code for org.ietf.jgss.GSSName.NT_ANONYMOUS definition code for org.ietf.jgss.GSSName.NT_ANONYMOUS
          Name type for representing an anonymous entity.
static Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid NT_EXPORT_NAME sample code for org.ietf.jgss.GSSName.NT_EXPORT_NAME definition code for org.ietf.jgss.GSSName.NT_EXPORT_NAME
          Name type used to indicate an exported name produced by the export method.
static Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid NT_HOSTBASED_SERVICE sample code for org.ietf.jgss.GSSName.NT_HOSTBASED_SERVICE definition code for org.ietf.jgss.GSSName.NT_HOSTBASED_SERVICE
          Oid indicating a host-based service name form.
static Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid NT_MACHINE_UID_NAME sample code for org.ietf.jgss.GSSName.NT_MACHINE_UID_NAME definition code for org.ietf.jgss.GSSName.NT_MACHINE_UID_NAME
          Name type to indicate a numeric user identifier corresponding to a user on a local system.
static Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid NT_STRING_UID_NAME sample code for org.ietf.jgss.GSSName.NT_STRING_UID_NAME definition code for org.ietf.jgss.GSSName.NT_STRING_UID_NAME
          Name type to indicate a string of digits representing the numeric user identifier of a user on a local system.
static Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid NT_USER_NAME sample code for org.ietf.jgss.GSSName.NT_USER_NAME definition code for org.ietf.jgss.GSSName.NT_USER_NAME
          Name type to indicate a named user on a local system.
 
Method Summary
 GSSName sample code for org.ietf.jgss.GSSName definition code for org.ietf.jgss.GSSName canonicalize sample code for org.ietf.jgss.GSSName.canonicalize(org.ietf.jgss.Oid) definition code for org.ietf.jgss.GSSName.canonicalize(org.ietf.jgss.Oid) (Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid  mech)
          Creates a name that is canonicalized for some mechanism.
 boolean equals sample code for org.ietf.jgss.GSSName.equals(org.ietf.jgss.GSSName) definition code for org.ietf.jgss.GSSName.equals(org.ietf.jgss.GSSName) (GSSName sample code for org.ietf.jgss.GSSName definition code for org.ietf.jgss.GSSName  another)
          Compares two GSSName objects to determine if they refer to the same entity.
 boolean equals sample code for org.ietf.jgss.GSSName.equals(java.lang.Object) definition code for org.ietf.jgss.GSSName.equals(java.lang.Object) (Object sample code for java.lang.Object definition code for java.lang.Object  another)
          Compares this GSSName object to another Object that might be a GSSName.
 byte[] export sample code for org.ietf.jgss.GSSName.export() definition code for org.ietf.jgss.GSSName.export() ()
          Returns a canonical contiguous byte representation of a mechanism name (MN), suitable for direct, byte by byte comparison by authorization functions.
 Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid getStringNameType sample code for org.ietf.jgss.GSSName.getStringNameType() definition code for org.ietf.jgss.GSSName.getStringNameType() ()
          Returns the name type of the printable representation of this name that can be obtained from the toString method.
 int hashCode sample code for org.ietf.jgss.GSSName.hashCode() definition code for org.ietf.jgss.GSSName.hashCode() ()
          Returns a hashcode value for this GSSName.
 boolean isAnonymous sample code for org.ietf.jgss.GSSName.isAnonymous() definition code for org.ietf.jgss.GSSName.isAnonymous() ()
          Tests if this name object represents an anonymous entity.
 boolean isMN sample code for org.ietf.jgss.GSSName.isMN() definition code for org.ietf.jgss.GSSName.isMN() ()
          Tests if this name object represents a Mechanism Name (MN).
 String sample code for java.lang.String definition code for java.lang.String toString sample code for org.ietf.jgss.GSSName.toString() definition code for org.ietf.jgss.GSSName.toString() ()
          Returns a textual representation of the GSSName object.
 

Field Detail

NT_HOSTBASED_SERVICE sample code for org.ietf.jgss.GSSName.NT_HOSTBASED_SERVICE

static final Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid  NT_HOSTBASED_SERVICE
Oid indicating a host-based service name form. It is used to represent services associated with host computers. This name form is constructed using two elements, "service" and "hostname", as follows: service@hostname.

It represents the following Oid value:
{ 1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 2(gss-host-based-services) }


NT_USER_NAME sample code for org.ietf.jgss.GSSName.NT_USER_NAME

static final Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid  NT_USER_NAME
Name type to indicate a named user on a local system.

It represents the following Oid value:
{ iso(1) member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) }


NT_MACHINE_UID_NAME sample code for org.ietf.jgss.GSSName.NT_MACHINE_UID_NAME

static final Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid  NT_MACHINE_UID_NAME
Name type to indicate a numeric user identifier corresponding to a user on a local system. (e.g. Uid).

It represents the following Oid value:
{ iso(1) member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) generic(1) machine_uid_name(2) }


NT_STRING_UID_NAME sample code for org.ietf.jgss.GSSName.NT_STRING_UID_NAME

static final Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid  NT_STRING_UID_NAME
Name type to indicate a string of digits representing the numeric user identifier of a user on a local system.

It represents the following Oid value:
{ iso(1) member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) }


NT_ANONYMOUS sample code for org.ietf.jgss.GSSName.NT_ANONYMOUS

static final Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid  NT_ANONYMOUS
Name type for representing an anonymous entity.

It represents the following Oid value:
{ 1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 3(gss-anonymous-name) }


NT_EXPORT_NAME sample code for org.ietf.jgss.GSSName.NT_EXPORT_NAME

static final Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid  NT_EXPORT_NAME
Name type used to indicate an exported name produced by the export method.

It represents the following Oid value:
{ 1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 4(gss-api-exported-name) }

Method Detail

equals sample code for org.ietf.jgss.GSSName.equals(org.ietf.jgss.GSSName) definition code for org.ietf.jgss.GSSName.equals(org.ietf.jgss.GSSName)

boolean equals(GSSName sample code for org.ietf.jgss.GSSName definition code for org.ietf.jgss.GSSName  another)
               throws GSSException sample code for org.ietf.jgss.GSSException definition code for org.ietf.jgss.GSSException 
Compares two GSSName objects to determine if they refer to the same entity.

Parameters:
another - the GSSName to compare this name with
Returns:
true if the two names contain at least one primitive element in common. If either of the names represents an anonymous entity, the method will return false.
Throws:
GSSException sample code for org.ietf.jgss.GSSException definition code for org.ietf.jgss.GSSException - when the names cannot be compared, containing the following major error codes: GSSException.BAD_NAMETYPE sample code for org.ietf.jgss.GSSException.BAD_NAMETYPE definition code for org.ietf.jgss.GSSException.BAD_NAMETYPE , GSSException.FAILURE sample code for org.ietf.jgss.GSSException.FAILURE definition code for org.ietf.jgss.GSSException.FAILURE

equals sample code for org.ietf.jgss.GSSName.equals(java.lang.Object) definition code for org.ietf.jgss.GSSName.equals(java.lang.Object)

boolean equals(Object sample code for java.lang.Object definition code for java.lang.Object  another)
Compares this GSSName object to another Object that might be a GSSName. The behaviour is exactly the same as in equals sample code for org.ietf.jgss.GSSName.equals(org.ietf.jgss.GSSName) definition code for org.ietf.jgss.GSSName.equals(org.ietf.jgss.GSSName) except that no GSSException is thrown; instead, false will be returned in the situation where an error occurs.

Overrides:
equals sample code for java.lang.Object.equals(java.lang.Object) definition code for java.lang.Object.equals(java.lang.Object) in class Object sample code for java.lang.Object definition code for java.lang.Object
Parameters:
another - the object to compare this name to
Returns:
true if the object to compare to is also a GSSName and the two names refer to the same entity.
See Also:
equals(GSSName) sample code for org.ietf.jgss.GSSName.equals(org.ietf.jgss.GSSName) definition code for org.ietf.jgss.GSSName.equals(org.ietf.jgss.GSSName)

hashCode sample code for org.ietf.jgss.GSSName.hashCode() definition code for org.ietf.jgss.GSSName.hashCode()

int hashCode()
Returns a hashcode value for this GSSName.

Overrides:
hashCode sample code for java.lang.Object.hashCode() definition code for java.lang.Object.hashCode() in class Object sample code for java.lang.Object definition code for java.lang.Object
Returns:
a hashCode value
See Also:
Object.equals(java.lang.Object) sample code for java.lang.Object.equals(java.lang.Object) definition code for java.lang.Object.equals(java.lang.Object) , Hashtable sample code for java.util.Hashtable definition code for java.util.Hashtable

canonicalize sample code for org.ietf.jgss.GSSName.canonicalize(org.ietf.jgss.Oid) definition code for org.ietf.jgss.GSSName.canonicalize(org.ietf.jgss.Oid)

GSSName sample code for org.ietf.jgss.GSSName definition code for org.ietf.jgss.GSSName  canonicalize(Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid  mech)
                     throws GSSException sample code for org.ietf.jgss.GSSException definition code for org.ietf.jgss.GSSException 
Creates a name that is canonicalized for some mechanism.

Parameters:
mech - the oid for the mechanism for which the canonical form of the name is requested.
Returns:
a GSSName that contains just one primitive element representing this name in a canonicalized form for the desired mechanism.
Throws:
GSSException sample code for org.ietf.jgss.GSSException definition code for org.ietf.jgss.GSSException - containing the following major error codes: GSSException.BAD_MECH sample code for org.ietf.jgss.GSSException.BAD_MECH definition code for org.ietf.jgss.GSSException.BAD_MECH , GSSException.BAD_NAMETYPE sample code for org.ietf.jgss.GSSException.BAD_NAMETYPE definition code for org.ietf.jgss.GSSException.BAD_NAMETYPE , GSSException.BAD_NAME sample code for org.ietf.jgss.GSSException.BAD_NAME definition code for org.ietf.jgss.GSSException.BAD_NAME , GSSException.FAILURE sample code for org.ietf.jgss.GSSException.FAILURE definition code for org.ietf.jgss.GSSException.FAILURE

export sample code for org.ietf.jgss.GSSName.export() definition code for org.ietf.jgss.GSSName.export()

byte[] export()
              throws GSSException sample code for org.ietf.jgss.GSSException definition code for org.ietf.jgss.GSSException 
Returns a canonical contiguous byte representation of a mechanism name (MN), suitable for direct, byte by byte comparison by authorization functions. If the name is not an MN, implementations may throw a GSSException with the NAME_NOT_MN status code. If an implementation chooses not to throw an exception, it should use some system specific default mechanism to canonicalize the name and then export it. Structurally, an exported name object consists of a header containing an OID identifying the mechanism that authenticated the name, and a trailer containing the name itself, where the syntax of the trailer is defined by the individual mechanism specification. The format of the header of the output buffer is specified in RFC 2743.

The exported name is useful when used in large access control lists where the overhead of creating a GSSName object on each name and invoking the equals method on each name from the ACL may be prohibitive.

Exported names may be re-imported by using the byte array factory method GSSManager.createName sample code for org.ietf.jgss.GSSManager.createName(byte[], org.ietf.jgss.Oid) definition code for org.ietf.jgss.GSSManager.createName(byte[], org.ietf.jgss.Oid) and specifying the NT_EXPORT_NAME as the name type object identifier. The resulting GSSName name will also be a MN.

Returns:
a byte[] containing the exported name. RFC 2743 defines the "Mechanism-Independent Exported Name Object Format" for these bytes.
Throws:
GSSException sample code for org.ietf.jgss.GSSException definition code for org.ietf.jgss.GSSException - containing the following major error codes: GSSException.BAD_NAME sample code for org.ietf.jgss.GSSException.BAD_NAME definition code for org.ietf.jgss.GSSException.BAD_NAME , GSSException.BAD_NAMETYPE sample code for org.ietf.jgss.GSSException.BAD_NAMETYPE definition code for org.ietf.jgss.GSSException.BAD_NAMETYPE , GSSException.FAILURE sample code for org.ietf.jgss.GSSException.FAILURE definition code for org.ietf.jgss.GSSException.FAILURE

toString sample code for org.ietf.jgss.GSSName.toString() definition code for org.ietf.jgss.GSSName.toString()

String sample code for java.lang.String definition code for java.lang.String  toString()
Returns a textual representation of the GSSName object. To retrieve the printed name format, which determines the syntax of the returned string, use the getStringNameType sample code for org.ietf.jgss.GSSName.getStringNameType() definition code for org.ietf.jgss.GSSName.getStringNameType() method.

Overrides:
toString sample code for java.lang.Object.toString() definition code for java.lang.Object.toString() in class Object sample code for java.lang.Object definition code for java.lang.Object
Returns:
a String representing this name in printable form.

getStringNameType sample code for org.ietf.jgss.GSSName.getStringNameType() definition code for org.ietf.jgss.GSSName.getStringNameType()

Oid sample code for org.ietf.jgss.Oid definition code for org.ietf.jgss.Oid  getStringNameType()
                      throws GSSException sample code for org.ietf.jgss.GSSException definition code for org.ietf.jgss.GSSException 
Returns the name type of the printable representation of this name that can be obtained from the toString method.

Returns:
an Oid representing the namespace of the name returned from the toString method.
Throws:
GSSException sample code for org.ietf.jgss.GSSException definition code for org.ietf.jgss.GSSException - containing the following major error codes: GSSException.FAILURE sample code for org.ietf.jgss.GSSException.FAILURE definition code for org.ietf.jgss.GSSException.FAILURE

isAnonymous sample code for org.ietf.jgss.GSSName.isAnonymous() definition code for org.ietf.jgss.GSSName.isAnonymous()

boolean isAnonymous()
Tests if this name object represents an anonymous entity.

Returns:
true if this is an anonymous name, false otherwise.

isMN sample code for org.ietf.jgss.GSSName.isMN() definition code for org.ietf.jgss.GSSName.isMN()

boolean isMN()
Tests if this name object represents a Mechanism Name (MN). An MN is a GSSName the contains exactly one mechanism's primitive name element.

Returns:
true if this is an MN, false otherwise.