https://openjdk.java.net/ 
/*
 * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package org.ietf.jgss;


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 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 and some standard types are defined 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);

 If a security manager is installed, in order to create a GSSName that contains a Kerberos name element without providing its realm, a ServicePermission must be granted and the service principal of the permission must minimally be inside the Kerberos name element's realm. For example, if the result of createName("user", NT_USER_NAME) contains a Kerberos name element user@EXAMPLE.COM, then a ServicePermission with service principal host/www.example.com@EXAMPLE.COM (and any action) must be granted. Otherwise, the creation will throw a GSSException containing the GSSException.FAILURE error code. 
Author:Mayank Upadhyay
See Also:
Since:1.4
/**
 * This interface encapsulates a single GSS-API principal entity. The
 * application obtains an implementation of this interface
 * through one of the <code>createName</code> methods that exist in the {@link
 * GSSManager 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)<p>
 *
 * 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 {@link Oid Oid's} and some standard types
 * are defined in this interface. The format of the names can be derived
 * based on the unique <code>Oid</code> of its name type.<p>
 *
 * Included below are code examples utilizing the <code>GSSName</code> interface.
 * The code below creates a <code>GSSName</code>, 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 <code>GSSName</code>.
 * <pre>
 *      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);
 *
 * </pre>
 * If a security manager is installed, in order to create a {@code GSSName}
 * that contains a Kerberos name element without providing its realm,
 * a {@link javax.security.auth.kerberos.ServicePermission ServicePermission}
 * must be granted and the service principal of the permission must minimally
 * be inside the Kerberos name element's realm. For example, if the result of
 * {@link GSSManager#createName(String, Oid) createName("user", NT_USER_NAME)}
 * contains a Kerberos name element {@code user@EXAMPLE.COM}, then
 * a {@code ServicePermission} with service principal
 * {@code host/www.example.com@EXAMPLE.COM} (and any action) must be granted.
 * Otherwise, the creation will throw a {@link GSSException} containing the
 * {@code GSSException.FAILURE} error code.
 *
 * @see #export()
 * @see #equals(GSSName)
 * @see GSSManager#createName(String, Oid)
 * @see GSSManager#createName(String, Oid, Oid)
 * @see GSSManager#createName(byte[], Oid)
 *
 * @author Mayank Upadhyay
 * @since 1.4
 */
public interface GSSName {

    
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:

 { iso(1) member-body(2) United
States(840) mit(113554) infosys(1) gssapi(2) generic(1) service_name(4)
}

/**
     * 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.<p>
     *
     * It represents the following Oid value:<br>
     *  <code>{ iso(1) member-body(2) United
     * States(840) mit(113554) infosys(1) gssapi(2) generic(1) service_name(4)
     * }</code>
     */
    public static final Oid NT_HOSTBASED_SERVICE
        = Oid.getInstance("1.2.840.113554.1.2.1.4");

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

/**
     * Name type to indicate a named user on a local system.<p>
     * It represents the following Oid value:<br>
     *  <code>{ iso(1) member-body(2) United
     * States(840) mit(113554) infosys(1) gssapi(2) generic(1) user_name(1)
     * }</code>
     */
    public static final Oid NT_USER_NAME
        = Oid.getInstance("1.2.840.113554.1.2.1.1");

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

/**
     * Name type to indicate a numeric user identifier corresponding to a
     * user on a local system. (e.g. Uid).<p>
     *
     *  It represents the following Oid value:<br>
     * <code>{ iso(1) member-body(2) United States(840) mit(113554)
     * infosys(1) gssapi(2) generic(1) machine_uid_name(2) }</code>
     */
    public static final Oid NT_MACHINE_UID_NAME
        = Oid.getInstance("1.2.840.113554.1.2.1.2");

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

/**
     * Name type to indicate a string of digits representing the numeric
     * user identifier of a user on a local system.<p>
     *
     * It represents the following Oid value:<br>
     * <code>{ iso(1) member-body(2) United
     * States(840) mit(113554) infosys(1) gssapi(2) generic(1)
     * string_uid_name(3) }</code>
     */
    public static final Oid NT_STRING_UID_NAME
        = Oid.getInstance("1.2.840.113554.1.2.1.3");

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

/**
     * Name type for representing an anonymous entity.<p>
     * It represents the following Oid value:<br>
     * <code>{ 1(iso), 3(org), 6(dod), 1(internet),
     * 5(security), 6(nametypes), 3(gss-anonymous-name) }</code>
     */
    public static final Oid NT_ANONYMOUS
        = Oid.getInstance("1.3.6.1.5.6.3");

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

/**
     * Name type used to indicate an exported name produced by the export
     * method.<p>
     *
     * It represents the following Oid value:<br> <code>{ 1(iso),
     * 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
     * 4(gss-api-exported-name) }</code>
     */
    public static final Oid NT_EXPORT_NAME
        = Oid.getInstance("1.3.6.1.5.6.4");

    
Compares two GSSName objects to determine if they refer to the
same entity.

Params:
  • another – the GSSName to compare this name with
Throws:
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.
/**
     * Compares two <code>GSSName</code> objects to determine if they refer to the
     * same entity.
     *
     * @param another the <code>GSSName</code> to compare this name with
     * @return 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 when the names cannot be compared, containing the following
     * major error codes:
     *         {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
     *         {@link GSSException#FAILURE GSSException.FAILURE}
     */
    public boolean equals(GSSName another) throws GSSException;

    
Compares this GSSName object to another Object that might be a
GSSName. The behaviour is exactly the same as in equals except that no GSSException is thrown; instead, false will be returned in the situation where an error occurs. 
Params:
  • another – the object to compare this name to
See Also:
Returns:true if the object to compare to is also a GSSName and the two
names refer to the same entity.
/**
     * Compares this <code>GSSName</code> object to another Object that might be a
     * <code>GSSName</code>. The behaviour is exactly the same as in {@link
     * #equals(GSSName) equals} except that no GSSException is thrown;
     * instead, false will be returned in the situation where an error
     * occurs.
     * @return true if the object to compare to is also a <code>GSSName</code> and the two
     * names refer to the same entity.
     * @param another the object to compare this name to
     * @see #equals(GSSName)
     */
    public boolean equals(Object another);

    
Returns a hashcode value for this GSSName.

Returns:a hashCode value
/**
     * Returns a hashcode value for this GSSName.
     *
     * @return a hashCode value
     */
    public int hashCode();

    
Creates a name that is canonicalized for some
mechanism.

Params:
  • mech – the oid for the mechanism for which the canonical form of
the name is requested.
Throws:
Returns:a GSSName that contains just one primitive
element representing this name in a canonicalized form for the desired
mechanism.
/**
     * Creates a name that is canonicalized for some
     * mechanism.
     *
     * @return a <code>GSSName</code> that contains just one primitive
     * element representing this name in a canonicalized form for the desired
     * mechanism.
     * @param mech the oid for the mechanism for which the canonical form of
     * the name is requested.
     *
     * @throws GSSException containing the following
     * major error codes:
     *         {@link GSSException#BAD_MECH GSSException.BAD_MECH},
     *         {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
     *         {@link GSSException#BAD_NAME GSSException.BAD_NAME},
     *         {@link GSSException#FAILURE GSSException.FAILURE}
     */
    public GSSName canonicalize(Oid mech) throws 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 and specifying the NT_EXPORT_NAME as the name type object identifier. The resulting GSSName name will
also be a MN.

Throws:
Returns:a byte[] containing the exported name. RFC 2743 defines the
"Mechanism-Independent Exported Name Object Format" for these bytes.
/**
     * 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.<p>
     *
     * The exported name is useful when used in large access control lists
     * where the overhead of creating a <code>GSSName</code> object on each
     * name and invoking the equals method on each name from the ACL may be
     * prohibitive.<p>
     *
     * Exported names may be re-imported by using the byte array factory
     * method {@link GSSManager#createName(byte[], Oid)
     * GSSManager.createName} and specifying the NT_EXPORT_NAME as the name
     * type object identifier. The resulting <code>GSSName</code> name will
     * also be a MN.
     *
     * @return a byte[] containing the exported name. RFC 2743 defines the
     * "Mechanism-Independent Exported Name Object Format" for these bytes.
     *
     * @throws GSSException containing the following
     * major error codes:
     *         {@link GSSException#BAD_NAME GSSException.BAD_NAME},
     *         {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
     *         {@link GSSException#FAILURE GSSException.FAILURE}
     */
    public byte[] export() throws GSSException;

    
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 method. 
Returns:a String representing this name in printable form.
/**
     * Returns a textual representation of the <code>GSSName</code> object.  To retrieve
     * the printed name format, which determines the syntax of the returned
     * string, use the {@link #getStringNameType() getStringNameType}
     * method.
     *
     * @return a String representing this name in printable form.
     */
    public String toString();

    
Returns the name type of the printable
representation of this name that can be obtained from the 
toString method.

Throws:
Returns:an Oid representing the namespace of the name returned
from the toString method.
/**
     * Returns the name type of the printable
     * representation of this name that can be obtained from the <code>
     * toString</code> method.
     *
     * @return an Oid representing the namespace of the name returned
     * from the toString method.
     *
     * @throws GSSException containing the following
     * major error codes:
     *         {@link GSSException#FAILURE GSSException.FAILURE}
     */
    public Oid getStringNameType() throws GSSException;

    
Tests if this name object represents an anonymous entity.

Returns:true if this is an anonymous name, false otherwise.
/**
     * Tests if this name object represents an anonymous entity.
     *
     * @return true if this is an anonymous name, false otherwise.
     */
    public boolean isAnonymous();

    
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.
/**
     * Tests if this name object represents a Mechanism Name (MN). An MN is
     * a GSSName the contains exactly one mechanism's primitive name
     * element.
     *
     * @return true if this is an MN, false otherwise.
     */
    public boolean isMN();

}