RFC 8353
Generic Security Service API Version 2: Java Bindings Update
6. Introduction to GSS-API Classes and Interfaces
This section presents a brief description of the classes and interfaces that constitute the GSS-API. The implementations of these are obtained from the CLASSPATH defined by the application. If Java GSS becomes part of the standard Java APIs, then these classes will be available by default on all systems as part of the JRE's system classes. This section also shows the corresponding RFC 2743 [RFC2743] functionality implemented by each of the classes. Detailed description of these classes and their methods is presented in Section 7.6.1. GSSManager Class
This abstract class serves as a factory to instantiate implementations of the GSS-API interfaces and also provides methods to make queries about underlying security mechanisms. A default implementation can be obtained using the static method getInstance(). Applications that desire to provide their own implementation of the GSSManager class can simply extend the abstract class themselves.
This class contains equivalents of the following RFC 2743 [RFC2743] routines: +----------------------------+-------------------------+------------+ | RFC 2743 Routine | Function | Section(s) | +----------------------------+-------------------------+------------+ | gss_import_name | Create an internal name | 7.1.5 - | | | from the supplied | 7.1.8 | | | information. | | | gss_acquire_cred | Acquire credential for | 7.1.9 - | | | use. | 7.1.11 | | gss_import_sec_context | Create a previously | 7.1.14 | | | exported context. | | | gss_indicate_mechs | List the mechanisms | 7.1.2 | | | supported by this GSS- | | | | API implementation. | | | gss_inquire_mechs_for_name | List the mechanisms | 7.1.4 | | | supporting the | | | | specified name type. | | | gss_inquire_names_for_mech | List the name types | 7.1.3 | | | supported by the | | | | specified mechanism. | | +----------------------------+-------------------------+------------+6.2. GSSName Interface
GSS-API names are represented in the Java bindings through the GSSName interface. 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 each name type. The following GSS-API routines are provided by the GSSName interface:
+-----------------------+------------------------------+------------+ | RFC 2743 Routine | Function | Section(s) | +-----------------------+------------------------------+------------+ | gss_display_name | Convert internal name | 7.2.6 | | | representation to text | | | | format. | | | gss_compare_name | Compare two internal names. | 7.2.2, | | | | 7.2.3 | | gss_release_name | Release resources associated | N/A | | | with the internal name. | | | gss_canonicalize_name | Convert an internal name to | 7.2.4 | | | a mechanism name. | | | gss_export_name | Convert a mechanism name to | 7.2.5 | | | export format. | | | gss_duplicate_name | Create a copy of the | N/A | | | internal name. | | +-----------------------+------------------------------+------------+ The gss_release_name call is not provided as Java does its own garbage collection. The gss_duplicate_name call is also redundant; the GSSName interface has no mutator methods that can change the state of the object, so it is safe for sharing across threads.6.3. GSSCredential Interface
The GSSCredential interface is responsible for the encapsulation of GSS-API credentials. Credentials identify a single entity and provide the necessary cryptographic information to enable the creation of a context on behalf of that entity. A single credential may contain multiple mechanism-specific credentials, each referred to as a credential element. The GSSCredential interface provides the functionality of the following GSS-API routines: +--------------------------+---------------------------+------------+ | RFC 2743 Routine | Function | Section(s) | +--------------------------+---------------------------+------------+ | gss_add_cred | Constructs credentials | 7.3.11 | | | incrementally. | | | gss_inquire_cred | Obtain information about | 7.3.3 - | | | credential. | 7.3.10 | | gss_inquire_cred_by_mech | Obtain per-mechanism | 7.3.4 - | | | information about a | 7.3.9 | | | credential. | | | gss_release_cred | Dispose of credentials | 7.3.2 | | | after use. | | +--------------------------+---------------------------+------------+
6.4. GSSContext Interface
This interface encapsulates the functionality of context-level calls required for security context establishment and management between peers as well as the per-message services offered to applications. A context is established between a pair of peers and allows the usage of security services on a per-message basis on application data. It is created over a single security mechanism. The GSSContext interface provides the functionality of the following GSS-API routines: +------------------------+-----------------------------+------------+ | RFC 2743 Routine | Function | Section(s) | +------------------------+-----------------------------+------------+ | gss_init_sec_context | Initiate the creation of a | 7.4.2 | | | security context with a | | | | peer. | | | gss_accept_sec_context | Accept a security context | 7.4.3 | | | initiated by a peer. | | | gss_delete_sec_context | Destroy a security context. | 7.4.5 | | gss_context_time | Obtain remaining context | 7.4.30 | | | time. | | | gss_inquire_context | Obtain context | 7.4.21 - | | | characteristics. | 7.4.35 | | gss_wrap_size_limit | Determine token-size limit | 7.4.6 | | | for gss_wrap. | | | gss_export_sec_context | Transfer security context | 7.4.11 | | | to another process. | | | gss_get_mic | Calculate a cryptographic | 7.4.9 | | | Message Integrity Code | | | | (MIC) for a message. | | | gss_verify_mic | Verify integrity on a | 7.4.10 | | | received message. | | | gss_wrap | Attach a MIC to a message | 7.4.7 | | | and optionally encrypt the | | | | message content. | | | gss_unwrap | Obtain a previously wrapped | 7.4.8 | | | application message | | | | verifying its integrity and | | | | optionally decrypting it. | | +------------------------+-----------------------------+------------+ The functionality offered by the gss_process_context_token routine has not been included in the Java bindings specification. The corresponding functionality of gss_delete_sec_context has also been modified to not return any peer tokens. This has been proposed in
accordance to the recommendations stated in RFC 2743 [RFC2743]. GSSContext does offer the functionality of destroying the locally stored context information.6.5. MessageProp Class
This helper class is used in the per-message operations on the context. An instance of this class is created by the application and then passed into the per-message calls. In some cases, the application conveys information to the GSS-API implementation through this object, and in other cases, the GSS-API returns information to the application by setting it in this object. See the description of the per-message operations wrap, unwrap, getMIC, and verifyMIC in the GSSContext interfaces for details.6.6. GSSException Class
Exceptions are used in the Java bindings to signal fatal errors to the calling applications. This replaces the major and minor codes used in the C-bindings specification as a method of signaling failures. The GSSException class handles both minor and major codes, as well as their translation into textual representation. All GSS-API methods are declared as throwing this exception. +--------------------+----------------------------+-----------------+ | RFC 2743 Routine | Function | Section | +--------------------+----------------------------+-----------------+ | gss_display_status | Retrieve textual | 7.8.5, 7.8.6, | | | representation of error | 7.8.9, 7.8.10 | | | codes. | | +--------------------+----------------------------+-----------------+6.7. Oid Class
This utility class is used to represent Universal Object Identifiers and their associated operations. GSS-API uses Object Identifiers to distinguish between security mechanisms and name types. This class, aside from being used whenever an Object Identifier is needed, implements the following GSS-API functionality: +-------------------------+-------------------------------+---------+ | RFC 2743 Routine | Function | Section | +-------------------------+-------------------------------+---------+ | gss_test_oid_set_member | Determine if the specified | 7.7.5 | | | OID is part of a set of OIDs. | | +-------------------------+-------------------------------+---------+
6.8. ChannelBinding Class
An instance of this class is used to specify channel-binding information to the GSSContext object before the start of a security context establishment. The application may use a byte array to specify application data to be used in the channel binding as well as to use instances of the InetAddress. InetAddress is currently the only address type defined within the Java platform and as such, it is the only one supported within the ChannelBinding class. Applications that use other types of addresses can include them as part of the application data.7. Detailed GSS-API Class Description
This section lists a detailed description of all the public methods that each of the GSS-API classes and interfaces MUST provide.7.1. public abstract class GSSManager
The GSSManager class is an abstract class that serves as a factory for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It also provides methods for applications to determine what mechanisms are available from the GSS implementation and what name types these mechanisms support. An instance of the default GSSManager subclass MAY be obtained through the static method getInstance(), but applications are free to instantiate other subclasses of GSSManager. All but one method in this class are declared abstract. This means that subclasses have to provide the complete implementation for those methods. The only exception to this is the static method getInstance(), which will have platform-specific code to return an instance of the default subclass. Platform providers of GSS are REQUIRED not to add any constructors to this class, whether the constructor is private, public, or protected. This will ensure that all subclasses invoke only the default constructor provided to the base class by the compiler. A subclass extending the GSSManager abstract class MAY be implemented as a modular provider-based layer that utilizes some well-known service provider specification. The GSSManager API provides the application with methods to set provider preferences on such an implementation. These methods also allow the implementation to throw a well-defined exception in case provider-based configuration is not supported. Applications that expect to be portable SHOULD be aware of this and recover cleanly by catching the exception.
It is envisioned that there will be three most common ways in which
providers will be used:
1) The application does not care about what provider is used (the
default case).
2) The application wants a particular provider to be used
preferentially, either for a particular mechanism or all the time,
irrespective of the mechanism.
3) The application wants to use the locally configured providers as
far as possible, but if support is missing for one or more
mechanisms, then it wants to fall back on its own provider.
The GSSManager class has two methods that enable these modes of
usage: addProviderAtFront() and addProviderAtEnd(). These methods
have the effect of creating an ordered list of <provider, OID> pairs
where each pair indicates a preference of provider for a given OID.
The use of these methods does not require any knowledge of whatever
service provider specification the GSSManager subclass follows. It
is hoped that these methods will serve the needs of most
applications. Additional methods MAY be added to an extended
GSSManager that could be part of a service provider specification
that is standardized later.
When neither of the methods is called, the implementation SHOULD
choose a default provider for each mechanism it supports.
7.1.1. getInstance
public static GSSManager getInstance()
Returns the default GSSManager implementation.
7.1.2. getMechs
public abstract Oid[] getMechs()
Returns an array of Oid objects indicating the mechanisms available
to GSS-API callers. A "null" value is returned when no mechanisms
are available (an example of this would be when mechanisms are
dynamically configured, and currently no mechanisms are installed).
7.1.3. getNamesForMech
public abstract Oid[] getNamesForMech(Oid mech) throws GSSException Returns name type OIDs supported by the specified mechanism. Parameters: mech The Oid object for the mechanism to query.7.1.4. getMechsForName
public abstract Oid[] getMechsForName(Oid nameType) Returns an array of Oid objects corresponding to the mechanisms that support the specific name type. "null" is returned when no mechanisms are found to support the specified name type. Parameters: nameType The Oid object for the name type.7.1.5. createName
public abstract GSSName createName(String nameStr, Oid nameType) throws GSSException Factory method to convert a contiguous string name from the specified namespace to a GSSName object. In general, the GSSName object created will not be an MN; two examples that are exceptions to this are when the namespace type parameter indicates NT_EXPORT_NAME or when the GSS-API implementation does not support multiple mechanisms. Parameters: nameStr The string representing a printable form of the name to create. nameType The OID specifying the namespace of the printable name is supplied. Note that nameType serves to describe and qualify the interpretation of the input nameStr; it does not necessarily imply a type for the output GSSName implementation. The "null" value can be used to specify that a mechanism-specific default printable syntax SHOULD be assumed by each mechanism that examines nameStr.
7.1.6. createName
public abstract GSSName createName(byte[] name, Oid nameType) throws GSSException Factory method to convert a contiguous byte array containing a name from the specified namespace to a GSSName object. In general, the GSSName object created will not be an MN; two examples that are exceptions to this are when the namespace type parameter indicates NT_EXPORT_NAME or when the GSS-API implementation is not a multi- mechanism. Parameters: name The byte array containing the name to create. nameType The OID specifying the namespace of the name supplied in the byte array. Note that nameType serves to describe and qualify the interpretation of the input name byte array; it does not necessarily imply a type for the output GSSName implementation. The "null" value can be used to specify that a mechanism-specific default syntax SHOULD be assumed by each mechanism that examines the byte array.7.1.7. createName
public abstract GSSName createName(String nameStr, Oid nameType, Oid mech) throws GSSException Factory method to convert a contiguous string name from the specified namespace to a GSSName object that is a mechanism name (MN). In other words, this method is a utility that does the equivalent of two steps: the createName described in Section 7.1.5 and also the GSSName.canonicalize() described in Section 7.2.4. Parameters: nameStr The string representing a printable form of the name to create.
nameType The OID specifying the namespace of the printable
name supplied. Note that nameType serves to
describe and qualify the interpretation of the
input nameStr; it does not necessarily imply a
type for the output GSSName implementation. The
"null" value can be used to specify that a
mechanism-specific default printable syntax
SHOULD be assumed when the mechanism examines
nameStr.
mech OID specifying the mechanism for which this name
should be created.
7.1.8. createName
public abstract GSSName createName(byte[] name, Oid nameType,
Oid mech) throws GSSException
Factory method to convert a contiguous byte array containing a name
from the specified namespace to a GSSName object that is an MN. In
other words, this method is a utility that does the equivalent of two
steps: the createName described in Section 7.1.6 and also the
GSSName.canonicalize() described in Section 7.2.4.
Parameters:
name The byte array representing the name to create.
nameType The OID specifying the namespace of the name
supplied in the byte array. Note that nameType
serves to describe and qualify the interpretation
of the input name byte array; it does not
necessarily imply a type for the output GSSName
implementation. The "null" value can be used to
specify that a mechanism-specific default syntax
SHOULD be assumed by each mechanism that examines
the byte array.
mech OID specifying the mechanism for which this name
should be created.
7.1.9. createCredential
public abstract GSSCredential createCredential(int usage) throws GSSException Factory method for acquiring default credentials. This will cause the GSS-API to use system-specific defaults for the set of mechanisms, name, and a DEFAULT lifetime. Parameters: 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.1.10. createCredential
public abstract GSSCredential createCredential(GSSName aName, int lifetime, Oid mech, int usage) throws GSSException Factory method for acquiring a single-mechanism credential. Parameters: aName Name of the principal for whom this credential is to be acquired. Use "null" to specify the default principal. lifetime The number of seconds that credentials should remain valid. 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 OID of the desired mechanism. Use "(Oid) null" to request the default mechanism. 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.1.11. createCredential
public abstract GSSCredential createCredential(GSSName aName, int lifetime, Oid[] mechs, int usage) throws GSSException Factory method for acquiring credentials over a set of mechanisms. Acquires credentials for each of the mechanisms specified in the array called mechs. To determine the list of mechanisms for which the acquisition of credentials succeeded, the caller should use the GSSCredential.getMechs() method. Parameters: aName Name of the principal for whom this credential is to be acquired. Use "null" to specify the default principal. lifetime The number of seconds that credentials should remain valid. Use GSSCredential.INDEFINITE_LIFETIME to request that the credentials have the maximum permitted lifetime. Use GSSCredential.DEFAULT_LIFETIME to request default credential lifetime. mechs The array of mechanisms over which the credential is to be acquired. Use "(Oid[]) null" for requesting a system-specific default set of mechanisms. 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.1.12. createContext
public abstract GSSContext createContext(GSSName peer, Oid mech, GSSCredential myCred, int lifetime) throws GSSException Factory method for creating a context on the initiator's side. Context flags may be modified through the mutator methods prior to calling GSSContext.initSecContext().
Parameters:
peer Name of the target peer.
mech OID of the desired mechanism. Use "(Oid) null"
to request the default mechanism.
myCred Credentials of the initiator. Use "null" to act
as a default initiator principal.
lifetime The request lifetime, in seconds, for the
context. Use GSSContext.INDEFINITE_LIFETIME and
GSSContext.DEFAULT_LIFETIME to request indefinite
or default context lifetime.
7.1.13. createContext
public abstract GSSContext createContext(GSSCredential myCred)
throws GSSException
Factory method for creating a context on the acceptor's side. The
context's properties will be determined from the input token supplied
to the accept method.
Parameters:
myCred Credentials for the acceptor. Use "null" to act
as a default acceptor principal.
7.1.14. createContext
public abstract GSSContext createContext(byte[] interProcessToken)
throws GSSException
Factory method for importing a previously exported context. The
context properties will be determined from the input token and can't
be modified through the set methods.
Parameters:
interProcessToken The token previously emitted from the export
method.
7.1.15. addProviderAtFront
public abstract void addProviderAtFront(Provider p, Oid mech) throws GSSException This method is used to indicate to the GSSManager that the application would like a particular provider to be used ahead of all others when support is desired for the given mechanism. When a value of "null" is used instead of an Oid object for the mechanism, the GSSManager MUST use the indicated provider ahead of all others no matter what the mechanism is. Only when the indicated provider does not support the needed mechanism should the GSSManager move on to a different provider. Calling this method repeatedly preserves the older settings but lowers them in preference thus forming an ordered list of provider and OID pairs that grows at the top. Calling addProviderAtFront with a null Oid will remove all previous preferences that were set for this provider in the GSSManager instance. Calling addProviderAtFront with a non-null Oid will remove any previous preference that was set using this mechanism and this provider together. If the GSSManager implementation does not support an SPI with a pluggable provider architecture, it SHOULD throw a GSSException with the status code GSSException.UNAVAILABLE to indicate that the operation is unavailable. Parameters: p The provider instance that should be used whenever support is needed for mech. mech The mechanism for which the provider is being set.
7.1.15.1. addProviderAtFront Example Code
Suppose an application desired that provider A always be checked first when any mechanism is needed, it would call: <CODE BEGINS> GSSManager mgr = GSSManager.getInstance(); // mgr may at this point have its own pre-configured list // of provider preferences. The following will prepend to // any such list: mgr.addProviderAtFront(A, null); <CODE ENDS> Now if it also desired that the mechanism of OID m1 always be obtained from provider B before the previous set A was checked, it would call: <CODE BEGINS> mgr.addProviderAtFront(B, m1); <CODE ENDS> The GSSManager would then first check with B if m1 was needed. In case B did not provide support for m1, the GSSManager would continue on to check with A. If any mechanism m2 is needed where m2 is different from m1, then the GSSManager would skip B and check with A directly. Suppose, at a later time, the following call is made to the same GSSManager instance: <CODE BEGINS> mgr.addProviderAtFront(B, null) <CODE ENDS> then the previous setting with the pair (B, m1) is subsumed by this and SHOULD be removed. Effectively, the list of preferences now becomes {(B, null), (A, null), ... //followed by the pre-configured list}. Please note, however, that the following call: <CODE BEGINS> mgr.addProviderAtFront(A, m3) <CODE ENDS> does not subsume the previous setting of (A, null), and the list will effectively become {(A, m3), (B, null), (A, null), ...}
7.1.16. addProviderAtEnd
public abstract void addProviderAtEnd(Provider p, Oid mech) throws GSSException This method is used to indicate to the GSSManager that the application would like a particular provider to be used if no other provider can be found that supports the given mechanism. When a value of "null" is used instead of an Oid object for the mechanism, the GSSManager MUST use the indicated provider for any mechanism. Calling this method repeatedly preserves the older settings but raises them above newer ones in preference, thus forming an ordered list of providers and OID pairs that grows at the bottom. Thus, the older provider settings will be utilized first before this one is. If there are any previously existing preferences that conflict with the preference being set here, then the GSSManager SHOULD ignore this request. If the GSSManager implementation does not support an SPI with a pluggable provider architecture, it SHOULD throw a GSSException with the status code GSSException.UNAVAILABLE to indicate that the operation is unavailable. Parameters: p The provider instance that should be used whenever support is needed for mech. mech The mechanism for which the provider is being set.7.1.16.1. addProviderAtEnd Example Code
Suppose an application desired that when a mechanism of OID m1 is needed, the system default providers always be checked first, and only when they do not support m1 should a provider A be checked. It would then make the call: <CODE BEGINS> GSSManager mgr = GSSManager.getInstance(); mgr.addProviderAtEnd(A, m1); <CODE ENDS>
Now, if it also desired that provider B be checked for all mechanisms
after all configured providers have been checked, it would then call:
<CODE BEGINS>
mgr.addProviderAtEnd(B, null);
<CODE ENDS>
Effectively, the list of preferences now becomes {..., (A, m1), (B,
null)}.
Suppose, at a later time, the following call is made to the same
GSSManager instance:
<CODE BEGINS>
mgr.addProviderAtEnd(B, m2)
<CODE ENDS>
then the previous setting with the pair (B, null) subsumes this;
therefore, this request SHOULD be ignored. The same would happen if
a request is made for the already existing pairs of (A, m1) or (B,
null).
Please note, however, that the following call:
<CODE BEGINS>
mgr.addProviderAtEnd(A, null)
<CODE ENDS>
is not subsumed by the previous setting of (A, m1), and the list will
effectively become {..., (A, m1), (B, null), (A, null)}.
7.1.17. Example Code
<CODE BEGINS>
GSSManager mgr = GSSManager.getInstance();
// What mechs are available to us?
Oid[] supportedMechs = mgr.getMechs();
// Set a preference for the provider to be used when support
// is needed for the mechanisms:
// "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1".
Oid krb = new Oid("1.2.840.113554.1.2.2");
Oid spkm1 = new Oid("1.3.6.1.5.5.1.1");
Provider p = (Provider) (new com.foo.security.Provider());
mgr.addProviderAtFront(p, krb); mgr.addProviderAtFront(p, spkm1); // What name types does this spkm implementation support? Oid[] nameTypes = mgr.getNamesForMech(spkm1); <CODE ENDS>
(page 45 continued on part 4)
