OpenJDK 27 · org.ietf.jgss.GSSName · APIdia, the JavaDoc alternative

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

Field Summary

Modifier and Type	Field and Description
public static final Oid	NT_ANONYMOUS Name type for representing an anonymous entity.
public static final Oid	NT_EXPORT_NAME Name type used to indicate an exported name produced by the export method.
public static final Oid	NT_HOSTBASED_SERVICE Oid indicating a host-based service name form.
public static final Oid	NT_MACHINE_UID_NAME Name type to indicate a numeric user identifier corresponding to a user on a local system.
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.
public static final Oid	NT_USER_NAME Name type to indicate a named user on a local system.

Method Summary

Modifier and Type	Method and Description
public GSSName	Returns: a `GSSName` that contains just one primitive element representing this name in a canonicalized form for the desired mechanism. canonicalize(Oid the oid for the mechanism for which the canonical form of the name is requested. mech) Creates a name that is canonicalized for some mechanism.
public boolean	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. equals(GSSName the `GSSName` to compare this name with another) Compares two `GSSName` objects to determine if they refer to the same entity.
public boolean	Returns: true if the object to compare to is also a `GSSName` and the two names refer to the same entity. equals(Object the object to compare this name to another) Compares this `GSSName` object to another Object that might be a `GSSName`.
public byte[]	Returns: a byte[] containing the exported name. RFC 2743 defines the "Mechanism-Independent Exported Name Object Format" for these bytes. export() Returns a canonical contiguous byte representation of a mechanism name (MN), suitable for direct, byte by byte comparison by authorization functions.
public Oid	Returns: an Oid representing the namespace of the name returned from the toString method. getStringNameType() Returns the name type of the printable representation of this name that can be obtained from the `toString` method.
public int	Returns: a hashcode value for this GSSName hashCode() Returns a hashcode value for this GSSName.
public boolean	Returns: true if this is an anonymous name, false otherwise. isAnonymous() Tests if this name object represents an anonymous entity.
public boolean	Returns: true if this is an MN, false otherwise. isMN() Tests if this name object represents a Mechanism Name (MN).
public String	Returns: a String representing this name in printable form. toString() Returns a textual representation of the `GSSName` object.

Field Detail

NT_ANONYMOUS back to summary

NT_ANONYMOUS	back to summary
public static final 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) }`

public static final 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 back to summary

NT_EXPORT_NAME	back to summary
public static final 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) }`

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

NT_HOSTBASED_SERVICE back to summary

NT_HOSTBASED_SERVICE	back to summary
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. 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) }`

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.

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_MACHINE_UID_NAME back to summary

NT_MACHINE_UID_NAME	back to summary
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 Oid 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_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 back to summary

NT_STRING_UID_NAME	back to summary
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 Oid 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_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_USER_NAME back to summary

NT_USER_NAME	back to summary
public static final 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) }`

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

Method Detail

canonicalize back to summary

canonicalize	back to summary
public GSSName canonicalize(Oid mech) throws GSSException Creates a name that is canonicalized for some mechanism. Parameters mech:Oid the oid for the mechanism for which the canonical form of the name is requested. Returns:GSSName a `GSSName` that contains just one primitive element representing this name in a canonicalized form for the desired mechanism. Exceptions GSSException: containing the following major error codes: `GSSException.BAD_MECH`, `GSSException.BAD_NAMETYPE`, `GSSException.BAD_NAME`, `GSSException.FAILURE`

public GSSName canonicalize(Oid mech) throws GSSException

Creates a name that is canonicalized for some mechanism.

Parameters

mech:Oid: the oid for the mechanism for which the canonical form of the name is requested.

Returns:GSSName

a GSSName that contains just one primitive element representing this name in a canonicalized form for the desired mechanism.

Exceptions

GSSException:: containing the following major error codes: GSSException.BAD_MECH, GSSException.BAD_NAMETYPE, GSSException.BAD_NAME, GSSException.FAILURE

equals back to summary

equals	back to summary
public boolean equals(GSSName another) throws GSSException Compares two `GSSName` objects to determine if they refer to the same entity. Parameters another:GSSName the `GSSName` to compare this name with Returns:boolean 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. Exceptions GSSException: when the names cannot be compared, containing the following major error codes: `GSSException.BAD_NAMETYPE`, `GSSException.FAILURE`

public boolean equals(GSSName another) throws GSSException

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

Parameters

another:GSSName: the GSSName to compare this name with

Returns:boolean

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.

Exceptions

GSSException:: when the names cannot be compared, containing the following major error codes: GSSException.BAD_NAMETYPE, GSSException.FAILURE

equals back to summary

equals	back to summary
public boolean equals(Object another) 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. Parameters another:Object the object to compare this name to Returns:boolean true if the object to compare to is also a `GSSName` and the two names refer to the same entity. Annotations @Override See Also `equals(GSSName)`

public boolean equals(Object another)

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.

Parameters

another:Object: the object to compare this name to

Returns:boolean

true if the object to compare to is also a GSSName and the two names refer to the same entity.

Annotations

@Override

See Also

equals(GSSName)

export back to summary

export	back to summary
public byte[] export() 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. Returns:byte[] a byte[] containing the exported name. RFC 2743 defines the "Mechanism-Independent Exported Name Object Format" for these bytes. Exceptions GSSException: containing the following major error codes: `GSSException.BAD_NAME`, `GSSException.BAD_NAMETYPE`, `GSSException.FAILURE`

public byte[] export() 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.

Returns:byte[]

a byte[] containing the exported name. RFC 2743 defines the "Mechanism-Independent Exported Name Object Format" for these bytes.

Exceptions

GSSException:: containing the following major error codes: GSSException.BAD_NAME, GSSException.BAD_NAMETYPE, GSSException.FAILURE

getStringNameType back to summary

getStringNameType	back to summary
public Oid getStringNameType() throws GSSException Returns the name type of the printable representation of this name that can be obtained from the `toString` method. Returns:Oid an Oid representing the namespace of the name returned from the toString method. Exceptions GSSException: containing the following major error codes: `GSSException.FAILURE`

public Oid getStringNameType() throws GSSException

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

Returns:Oid

an Oid representing the namespace of the name returned from the toString method.

Exceptions

GSSException:: containing the following major error codes: GSSException.FAILURE

hashCode	back to summary
public int hashCode() Returns a hashcode value for this GSSName. Returns:int a hashcode value for this GSSName Annotations @Override

hashCode

back to summary

public int hashCode()

Returns a hashcode value for this GSSName.

Returns:int

a hashcode value for this GSSName

Annotations

@Override

isAnonymous	back to summary
public boolean isAnonymous() Tests if this name object represents an anonymous entity. Returns:boolean true if this is an anonymous name, false otherwise.

isAnonymous

back to summary

public boolean isAnonymous()

Tests if this name object represents an anonymous entity.

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

isMN	back to summary
public 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:boolean true if this is an MN, false otherwise.

isMN

back to summary

public 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:boolean: true if this is an MN, false otherwise.

toString back to summary

toString	back to summary
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, use the `getStringNameType` method. Returns:String a String representing this name in printable form.

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, use the getStringNameType method.

Returns:String: a String representing this name in printable form.

public Interface GSSName

Field Summary

Method Summary

Field Detail

Method Detail