7.2.  public interface GSSName

   This interface encapsulates a single GSS-API principal entity.
   Different name formats and their definitions are identified with
   Universal OIDs.  The format of the names can be derived based on the
   unique OID of its namespace type.

7.2.1.  Static Constants

   public static final 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

   Values for the "service" element are registered with the IANA.  It
   represents the following value: { iso(1) member-body(2) United
   States(840) mit(113554) infosys(1) gssapi(2) generic(1)
   service_name(4) }

   public static final Oid NT_USER_NAME

   Name type to indicate a named user on a local system.  It represents
   the following value: { iso(1) member-body(2) United States(840)
   mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) }

   public static final 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
   value: { iso(1) member-body(2) United States(840) mit(113554)
   infosys(1) gssapi(2) generic(1) machine_uid_name(2) }

   public static final 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 value: { iso(1) member-body(2) United States(840)
   mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) }

   public static final Oid NT_ANONYMOUS

   Name type for representing an anonymous entity.  It represents the
   following value: { iso(1), org(3), dod(6), internet(1), security(5),
   nametypes(6), gss-anonymous-name(3) }

   public static final Oid NT_EXPORT_NAME

   Name type used to indicate an exported name produced by the export
   method.  It represents the following value: { iso(1), org(3), dod(6),
   internet(1), security(5), nametypes(6), gss-api-exported-name(4) }

7.2.2.  equals

   public boolean equals(GSSName another) throws GSSException

   Compares two GSSName objects to determine whether they refer to the
   same entity.  This method MAY throw a GSSException when the names
   cannot be compared.  If either of the names represents an anonymous
   entity, the method will return "false".

   Parameters:

   another             GSSName object with which to compare.

7.2.3.  equals

   public boolean equals(Object another)

   A variation of the equals method, described in Section 7.2.2, that is
   provided to override the Object.equals() method that the implementing
   class will inherit.  The behavior is exactly the same as that in
   Section 7.2.2 except that no GSSException is thrown; instead, "false"
   will be returned in the situation where an error occurs.  (Note that
   the Java language specification requires that two objects that are
   equal according to the equals(Object) method MUST return the same
   integer result when the hashCode() method is called on them.)

   Parameters:

   another             GSSName object with which to compare.

7.2.4.  canonicalize

   public GSSName canonicalize(Oid mech) throws GSSException

   Creates an MN from an arbitrary internal name.  This is equivalent to
   using the factory methods described in Sections 7.1.7 or 7.1.8 that
   take the mechanism name as one of their parameters.

   Parameters:

   mech                The OID for the mechanism for which the canonical
                       form of the name is requested.

7.2.5.  export

   public byte[] export() throws GSSException

   Returns a canonical contiguous byte representation of an 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.  The format of
   the header of the output buffer is specified in RFC 2743 [RFC2743].

7.2.6.  toString

   public String toString()

   Returns a textual representation of the GSSName object.  To retrieve
   the printed name format, which determines the syntax of the returned
   string, the getStringNameType method can be used.

7.2.7.  getStringNameType

   public Oid getStringNameType() throws GSSException

   Returns the OID representing the type of name returned through the
   toString method.  Using this OID, the syntax of the printable name
   can be determined.

7.2.8.  isAnonymous

   public boolean isAnonymous()

   Tests if this name object represents an anonymous entity.  Returns
   "true" if this is an anonymous name.

7.2.9.  isMN

   public boolean isMN()

   Tests if this name object contains only one mechanism element and is
   thus a mechanism name as defined by RFC 2743 [RFC2743].

7.2.10.  Example Code

   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, and then re-imports to obtain a new GSSName.

   <CODE BEGINS>
   GSSManager mgr = GSSManager.getInstance();

   // create a host-based service name
   GSSName name = mgr.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 = mgr.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 the name
   byte[] exportName = mechName.export();

   // create a new name object from the exported buffer
   GSSName newName = mgr.createName(exportName,
                     GSSName.NT_EXPORT_NAME);
   <CODE ENDS>

7.3.  public interface GSSCredential implements Cloneable

   This interface encapsulates the GSS-API credentials for an entity.  A
   credential contains all the necessary cryptographic information to
   enable the creation of a context on behalf of the entity that it
   represents.  It MAY contain multiple, distinct, mechanism-specific
   credential elements, each containing information for a specific
   security mechanism, but all referring to the same entity.

   A credential MAY be used to perform context initiation, acceptance,
   or both.

   GSS-API implementations MUST impose a local access-control policy on
   callers to prevent unauthorized callers from acquiring credentials to
   which they are not entitled.  GSS-API credential creation is not
   intended to provide a "login to the network" function, as such a
   function would involve the creation of new credentials rather than
   merely acquiring a handle to existing credentials.  Such functions,
   if required, SHOULD be defined in implementation-specific extensions
   to the API.

   If credential acquisition is time-consuming for a mechanism, the
   mechanism MAY choose to delay the actual acquisition until the
   credential is required (e.g., by GSSContext).  Such mechanism-
   specific implementation decisions SHOULD be invisible to the calling
   application; thus, the query methods immediately following the
   creation of a credential object MUST return valid credential data and
   may therefore incur the overhead of a deferred credential
   acquisition.

   Applications will create a credential object passing the desired
   parameters.  The application can then use the query methods to obtain
   specific information about the instantiated credential object
   (equivalent to the gss_inquire routines).  When the credential is no
   longer needed, the application SHOULD call the dispose (equivalent to
   gss_release_cred) method to release any resources held by the
   credential object and to destroy any cryptographically sensitive
   information.

   Classes implementing this interface also implement the Cloneable
   interface.  This indicates that the class will support the clone()
   method that will allow the creation of duplicate credentials.  This
   is useful when called just before the add() call to retain a copy of
   the original credential.

7.3.1.  Static Constants

   public static final int INITIATE_AND_ACCEPT

   Credential usage flag requesting that it be able to be used for both
   context initiation and acceptance.  The value of this constant is 0.

   public static final int INITIATE_ONLY

   Credential usage flag requesting that it be able to be used for
   context initiation only.  The value of this constant is 1.

   public static final int ACCEPT_ONLY

   Credential usage flag requesting that it be able to be used for
   context acceptance only.  The value of this constant is 2.

   public static final int DEFAULT_LIFETIME

   A lifetime constant representing the default credential lifetime.
   The value of this constant is 0.

   public static final int INDEFINITE_LIFETIME

   A lifetime constant representing indefinite credential lifetime.  The
   value of this constant is the maximum integer value in Java --
   Integer.MAX_VALUE.

7.3.2.  dispose

   public void dispose() throws GSSException

   Releases any sensitive information that the GSSCredential object may
   be containing.  Applications SHOULD call this method as soon as the
   credential is no longer needed to minimize the time any sensitive
   information is maintained.

7.3.3.  getName

   public GSSName getName() throws GSSException

   Retrieves the name of the entity that the credential asserts.

7.3.4.  getName

   public GSSName getName(Oid mechOID) throws GSSException

   Retrieves a mechanism name of the entity that the credential asserts.
   Equivalent to calling canonicalize() on the name returned by
   Section 7.3.3.

   Parameters:

   mechOID             The mechanism for which information should be
                       returned.

7.3.5.  getRemainingLifetime

   public int getRemainingLifetime() throws GSSException

   Returns the remaining lifetime in seconds for a credential.  The
   remaining lifetime is the minimum lifetime for any of the underlying
   credential mechanisms.  A return value of
   GSSCredential.INDEFINITE_LIFETIME indicates that the credential does
   not expire.  A return value of 0 indicates that the credential is
   already expired.

7.3.6.  getRemainingInitLifetime

   public int getRemainingInitLifetime(Oid mech) throws GSSException

   Returns the remaining lifetime in seconds for the credential to
   remain capable of initiating security contexts under the specified
   mechanism.  A return value of GSSCredential.INDEFINITE_LIFETIME
   indicates that the credential does not expire for context initiation.
   A return value of 0 indicates that the credential is already expired.

   Parameters:

   mechOID             The mechanism for which information should be
                       returned.

7.3.7.  getRemainingAcceptLifetime

   public int getRemainingAcceptLifetime(Oid mech) throws GSSException

   Returns the remaining lifetime in seconds for the credential to
   remain capable of accepting security contexts under the specified
   mechanism.  A return value of GSSCredential.INDEFINITE_LIFETIME
   indicates that the credential does not expire for context acceptance.
   A return value of 0 indicates that the credential is already expired.

   Parameters:

   mechOID             The mechanism for which information should be
                       returned.

7.3.8.  getUsage

   public int getUsage() throws GSSException

   Returns the credential usage flag as a union over all mechanisms.
   The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0),
   GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2).

   Specifically, GSSCredential.INITIATE_AND_ACCEPT(0) SHOULD be returned
   as long as there exists one credential element allowing context
   initiation and one credential element allowing context acceptance.
   These two credential elements are not necessarily the same one, nor
   do they need to use the same mechanism(s).

7.3.9.  getUsage

   public int getUsage(Oid mechOID) throws GSSException

   Returns the credential usage flag for the specified mechanism only.
   The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0),
   GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2).

   Parameters:

   mechOID             The mechanism for which information should be
                       returned.

7.3.10.  getMechs

   public Oid[] getMechs() throws GSSException

   Returns an array of mechanisms supported by this credential.

7.3.11.  add

   public void add(GSSName aName, int initLifetime, int acceptLifetime,
                   Oid mech, int usage) throws GSSException

   Adds a mechanism-specific credential element to an existing
   credential.  This method allows the construction of credentials one
   mechanism at a time.

   This routine is envisioned to be used mainly by context acceptors
   during the creation of acceptance credentials, which are to be used
   with a variety of clients using different security mechanisms.

   This routine adds the new credential element "in-place".  To add the
   element in a new credential, first call clone() to obtain a copy of
   this credential, then call its add() method.

   Parameters:

   aName               Name of the principal for whom this credential is
                       to be acquired.  Use "null" to specify the
                       default principal.

   initLifetime        The number of seconds that credentials should
                       remain valid for initiating security contexts.
                       Use GSSCredential.INDEFINITE_LIFETIME to request
                       that the credentials have the maximum permitted
                       lifetime.  Use GSSCredential.DEFAULT_LIFETIME to
                       request default credential lifetime.

   acceptLifetime      The number of seconds that credentials should
                       remain valid for accepting security contexts.

                       Use GSSCredential.INDEFINITE_LIFETIME to request
                       that the credentials
                       have the maximum permitted lifetime.  Use
                       GSSCredential.DEFAULT_LIFETIME to request default
                       credential lifetime.

   mech                The mechanisms over which the credential is to be
                       acquired.

   usage               The intended usage for this credential object.
                       The value of this parameter MUST be one of:

                       GSSCredential.INITIATE_AND_ACCEPT(0),
                       GSSCredential.INITIATE_ONLY(1), or
                       GSSCredential.ACCEPT_ONLY(2)

7.3.12.  equals

   public boolean equals(Object another)

   Tests if this GSSCredential refers to the same entity as the supplied
   object.  The two credentials MUST be acquired over the same
   mechanisms and MUST refer to the same principal.  Returns "true" if
   the two GSSCredentials refer to the same entity, or "false"

   otherwise.  (Note that the Java language specification [JLS] requires
   that two objects that are equal according to the equals(Object)
   method MUST return the same integer result when the hashCode() method
   is called on them.)

   Parameters:

   another             Another GSSCredential object for comparison.

7.3.13.  Example Code

   This example code demonstrates the creation of a GSSCredential
   implementation for a specific entity, querying of its fields, and its
   release when it is no longer needed.

   <CODE BEGINS>
   GSSManager mgr = GSSManager.getInstance();

   // start by creating a name object for the entity
   GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME);

   // now acquire credentials for the entity
   GSSCredential cred = mgr.createCredential(name,
              GSSCredential.INDEFINITE_LIFETIME,
              (Oid[])null,
              GSSCredential.ACCEPT_ONLY);

   // display credential information - name, remaining lifetime,
   // and the mechanisms it has been acquired over
   print(cred.getName().toString());
   print(cred.getRemainingLifetime());

   Oid[] mechs = cred.getMechs();
   if (mechs != null) {
      for (int i = 0; i < mechs.length; i++)
          print(mechs[i].toString());
   }
   // release system resources held by the credential
   cred.dispose();
   <CODE ENDS>