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.- Since:
- 1.4
- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionstatic final Oid
Name type for representing an anonymous entity.static final Oid
Name type used to indicate an exported name produced by the export method.static final Oid
Oid indicating a host-based service name form.static final Oid
Name type to indicate a numeric user identifier corresponding to a user on a local system.static final Oid
Name type to indicate a string of digits representing the numeric user identifier of a user on a local system.static final Oid
Name type to indicate a named user on a local system. -
Method Summary
Modifier and TypeMethodDescriptioncanonicalize
(Oid mech) Creates a name that is canonicalized for some mechanism.boolean
Compares thisGSSName
object to another Object that might be aGSSName
.boolean
Compares twoGSSName
objects to determine if they refer to the same entity.byte[]
export()
Returns a canonical contiguous byte representation of a mechanism name (MN), suitable for direct, byte by byte comparison by authorization functions.Returns the name type of the printable representation of this name that can be obtained from thetoString
method.int
hashCode()
Returns a hashcode value for this GSSName.boolean
Tests if this name object represents an anonymous entity.boolean
isMN()
Tests if this name object represents a Mechanism Name (MN).toString()
Returns a textual representation of theGSSName
object.
-
Field Details
-
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:
{ iso(1) member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) generic(1) service_name(4) }
-
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
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
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
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
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 Details
-
equals
Compares twoGSSName
objects to determine if they refer to the same entity.- Parameters:
another
- theGSSName
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
- when the names cannot be compared, containing the following major error codes:GSSException.BAD_NAMETYPE
,GSSException.FAILURE
-
equals
Compares thisGSSName
object to another Object that might be aGSSName
. The behaviour is exactly the same as inequals
except that no GSSException is thrown; instead, false will be returned in the situation where an error occurs. -
hashCode
int hashCode()Returns a hashcode value for this GSSName. -
canonicalize
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
- containing the following major error codes:GSSException.BAD_MECH
,GSSException.BAD_NAMETYPE
,GSSException.BAD_NAME
,GSSException.FAILURE
-
export
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 resultingGSSName
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
- containing the following major error codes:GSSException.BAD_NAME
,GSSException.BAD_NAMETYPE
,GSSException.FAILURE
-
toString
String toString()Returns a textual representation of theGSSName
object. To retrieve the printed name format, which determines the syntax of the returned string, use thegetStringNameType
method. -
getStringNameType
Returns the name type of the printable representation of this name that can be obtained from thetoString
method.- Returns:
- an Oid representing the namespace of the name returned from the toString method.
- Throws:
GSSException
- containing the following major error codes:GSSException.FAILURE
-
isAnonymous
boolean isAnonymous()Tests if this name object represents an anonymous entity.- Returns:
- true if this is an anonymous name, false otherwise.
-
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.
-