Generic Security Service API Version 2 : Java Bindings
obsoleted by
- rfc-5653 — Generic Security Service API Version 2: Java Bindings Update
Extracted elements (30)
Java's automatic garbage collection eliminates the need for several explicit GSS-API management routines present in the C bindings: gss_release_name, gss_release_oid_set, gss_create_empty_oid_set, gss_add_oid_set_member, and gss_duplicate_name are all absent from the Java API.
The GSS-API Java binding leverages the Java Cryptography Architecture (JCA) provider model to support pluggable security mechanisms. Providers can be added system-wide or per-instance of GSSManager, enabling applications to use Kerberos v5, SPKM, or other mechanisms without code changes. The SPI specification for provider discovery is deferred and not mandatory for adoption.
The Java binding uses exceptions (GSSException) to replace the major/minor status code output parameters used in the C bindings for fatal errors. Supplementary (non-fatal) per-message status codes are returned via the MessageProp object instead of exceptions, since exceptions are inappropriate for informational warnings.
The Oid class instances are intentionally immutable — no mutator methods are defined — so that Oid objects can be treated as shared statics without defensive copying. This simplifies memory management and avoids aliasing bugs in multi-mechanism environments.
The gss_process_context_token routine from RFC 2743 has no equivalent in the Java bindings. Additionally, gss_delete_sec_context (mapped to GSSContext.dispose()) has been modified to not return any peer tokens, in accordance with RFC 2743 recommendations.
The results of GSSName.equals() (comparing unauthenticated internal names) will in general differ from those obtained by canonicalize+export followed by byte-array comparison (which tests whether a specific mechanism authenticates them as the same principal). These operations agree only for mechanism names (MNs).
There is no guarantee that calling toString() on a GSSName will produce the same string form as the original imported string name, nor that namespace identifiers survive unchanged through the internal name form. For example, a mechanism may store an X.500 name internally when presented with a DNS name.
Applications SHOULD NOT use confidential data as channel-binding components because some mechanisms may include the actual channel binding data in the token (rather than just a MIC), which could expose it.
Applications using inter-process tokens to transfer security contexts MUST take appropriate steps to protect these tokens in transit. Interprocess tokens may contain sensitive data including cryptographic keys from the original security context.
Callers using stream-based GSS-API methods are responsible for ensuring that the supplied streams will not block, or expect to block until a full token is processed. Only a single GSS-API token will be processed per invocation of the stream-based method.
If the application instructs the GSSContext object that delegation is not desired, then the implementation MUST NOT permit delegation to occur. This is an exception to the general rule that a mechanism may enable services even if not requested — delegation may only be provided at the explicit request of the application.
Platform providers of GSS are required not to add any constructors to the GSSManager class (private, public, or protected). This ensures that all subclasses invoke only the default constructor provided to the base class by the compiler.
The classes and interfaces defined in this document MUST reside in the package called 'org.ietf.jgss'. Applications wishing to use this API should import this package name.
When null is passed as the GSSCredential to createContext, the implementation SHOULD follow a defined priority order for default principal selection: (1) single authorized principal, (2) default network identity, (3) mapped local identity, (4) user-configurable default.
When using the equals method of the GSSName interface and one of the operands is a GSSName instance representing an anonymous entity, the method MUST return false.
Anonymous authentication is provided to allow a client to authenticate a peer service without revealing its own identity, addressing privacy concerns about the specific inquiries made or avoidance of being tracked. Many mechanisms do not support anonymity; the application is always informed if the service is unavailable.
ChannelBinding encapsulates channel binding information for a GSSContext, consisting of an optional initiator InetAddress, optional acceptor InetAddress, and an optional application-data byte array. It must be set before the first call to init or accept. InetAddress is the only address type supported in the Java platform binding.
GSSContext is the central interface encapsulating one end of a GSS-API security context. It provides context establishment (initSecContext, acceptSecContext), per-message protection (wrap, unwrap, getMIC, verifyMIC), context export for inter-process transfer, and accessor methods for all negotiated context attributes.
GSSCredential is an interface (implementing Cloneable) that encapsulates GSS-API credentials for one or more mechanisms. It provides methods for querying remaining lifetime (getRemainingLifetime, getRemainingInitLifetime, getRemainingAcceptLifetime), usage type, and incrementally adding credential elements via add().
GSSException extends Exception and replaces the major/minor status code return pattern from the C bindings. It carries a major GSS status code (integer 1–20) and an optional mechanism-specific minor status code, with getMajorString() and getMinorString() for human-readable messages.
GSSManager is an abstract factory class for instantiating GSSName, GSSCredential, and GSSContext objects. It provides getMechs(), getNamesForMech(), getMechsForName(), and provider-preference methods addProviderAtFront() and addProviderAtEnd(). A default instance is obtained via the static getInstance() method.
GSSName is an interface representing a principal identity in GSS-API. It supports multiple simultaneous namespace representations internally (for multi-mechanism environments), export to a canonical byte-array form (NT_EXPORT_NAME), canonicalization to a mechanism name (MN), and equality testing via equals().
MessageProp is a helper class passed into per-message GSSContext operations (wrap, unwrap, getMIC, verifyMIC). It carries QOP, privacy flag, minor status, and supplementary status flags: isDuplicateToken, isOldToken, isUnseqToken, isGapToken.
The Oid class represents ASN.1 Object Identifiers used to identify security mechanisms and name types. Instances are immutable and can be constructed from dot-notation strings (e.g., '1.3.6.1.5.6.2') or from DER-encoded byte arrays. getDER() returns the DER encoding; containedIn() tests membership in an Oid array.
Anonymous authentication contexts reveal no initiator identity to the acceptor; getSrcName() returns a reserved implementation-defined name. The printable form of an anonymous name must be syntactically distinguishable from any valid principal name to prevent spoofing in audit logs.
Channel bindings are verified by computing a MIC over the concatenated initiator address, acceptor address, and application data, and comparing it with the MIC in the context-establishment token. Mismatch causes acceptSecContext to throw GSSException with major code BAD_BINDINGS.
Interprocess tokens may contain sensitive data from the original security context, including cryptographic keys. The application is responsible for ensuring that these tokens are protected in transit and transferred only to trustworthy processes.
A GSSContext proceeds through three phases: (1) unestablished — initiator sets request flags (requestMutualAuth, requestCredDeleg, requestConf, etc.) and calls initSecContext/acceptSecContext iteratively exchanging tokens; (2) established — isEstablished() returns true and per-message services (wrap/getMIC) become available; (3) invalidated — after dispose() or export(), the object is unusable.
Authentication tokens and interprocess tokens are represented as Java byte arrays (opaque octet strings). Overloaded stream-based method variants are also provided, where the stream is expected to contain a single complete GSS-API token with a definite start and end.
Exported GSSName (NT_EXPORT_NAME) is a contiguous byte array with a header containing an OID identifying the authenticating mechanism, followed by a trailer whose syntax is mechanism-defined, as specified in RFC 2743. This form is suitable for direct byte-by-byte comparison in ACL checks.