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.