Generic Security Service API Version 2: Java Bindings Update
obsoletes
- rfc-5653 — Generic Security Service API Version 2: Java Bindings Update
Extracted elements (30)
Java exceptions replace the C-bindings major/minor status code return mechanism for signaling fatal errors. Supplementary non-fatal status (duplicate/old/out-of-sequence tokens) is returned via the MessageProp object rather than exceptions, since exceptions are not appropriate for informational or warning-level conditions.
Java's automatic garbage collection and immutable Oid objects eliminate the need for several C-binding routines: gss_release_name, gss_duplicate_name, gss_create_empty_oid_set, gss_release_oid_set, and gss_add_oid_set_member are not present in the Java API.
RFC 8353 obsoletes RFC 5653 by adding a new output token field to the GSSException class, so that when initSecContext or acceptSecContext fail, the mechanism has a chance to emit an error token that can be sent to the peer for debugging or informational purposes.
Stream-based GSSContext methods are removed in this version. This simplifies the API by eliminating overloads that accepted InputStream/OutputStream parameters, which duplicated functionality available through byte-array variants.
The GSS-API Java bindings leverage the Java Cryptography Architecture (JCA) provider model to support plugability of security mechanisms. Mechanisms can be added system-wide or per-instance of the GSS-API, allowing seamless switching between implementations without application changes.
RFC 8353 obsoletes RFC 5653. The two changes are: (1) a new getOutputToken() method on GSSException enabling error tokens from failed initSecContext/acceptSecContext to be forwarded to the peer, and (2) removal of all stream-based GSSContext methods that accepted InputStream/OutputStream parameters.
The GSSContext interface does not include gss_process_context_token functionality, and gss_delete_sec_context is modified to not return any peer tokens, in accordance with RFC 2743 recommendations.
All principal identities asserted by a single GSS-API credential SHOULD belong to the same entity. A GSSName object MAY contain multiple names from different namespaces, but all names SHOULD refer to the same entity.
Applications SHOULD NOT use confidential data as channel-binding components because some mechanisms may include the actual channel-binding data (not just a MIC) in the token, potentially exposing it to the peer.
Applications using inter-process tokens to transfer security contexts MUST take appropriate steps to protect these tokens in transit, as they MAY contain sensitive data including cryptographic keys.
If a GSSException is thrown during context establishment, the context negotiation has failed and the GSSContext object MUST be abandoned. If thrown in a per-message call, the context MAY remain useful.
If any retrieved context attribute does not match the desired value but is necessary for the application protocol, the application SHOULD destroy the security context and not use it for application traffic.
If the application instructs the GSSContext object that delegation is not desired, the implementation MUST NOT permit delegation to occur. Delegation may only be provided at the explicit request of the application; this overrides the general rule that mechanisms may enable unrequested services.
Platform providers of GSS are REQUIRED not to add any constructors to the GSSManager class (whether private, public, or protected), ensuring that all subclasses invoke only the default constructor provided by the compiler.
When using the equals method of GSSName and one operand is a GSSName representing an anonymous entity, the method MUST return 'false'.
Whenever the application wishes to omit an optional parameter, the 'null' value SHALL be used. Method overloading is also used as a technique to indicate default parameters.
Anonymous authentication (requestAnonymity) allows a context initiator to authenticate without revealing its identity to the acceptor. The printable form of an anonymous GSSName SHOULD imply anonymity (e.g., '<anonymous>'), and the associated name-type OID MUST be NT_ANONYMOUS. Anonymous names MUST compare unequal to all other names including other anonymous names.
All GSS-API classes and interfaces reside in the package 'org.ietf.jgss'. Applications must import this package to use the API.
ChannelBinding encapsulates channel-binding information (optional InetAddress for initiator/acceptor and application-specific byte array) to bind a GSS-API context to a specific communications channel. The mechanism computes a MIC over the concatenated binding data and includes it in the context-establishment token.
GSS Status Codes are static integer constants in GSSException ranging from BAD_BINDINGS (1) to NAME_NOT_MN (18) for fatal generic errors, plus DUPLICATE_TOKEN (19), OLD_TOKEN (20), UNSEQ_TOKEN (21), and GAP_TOKEN (22) which are fatal only during context establishment and supplementary during per-message calls.
GSSContext is the central interface encapsulating security context state for one peer, including cryptographic keys and sequence numbers. It provides initSecContext and acceptSecContext for establishment, wrap/unwrap and getMIC/verifyMIC for per-message protection, and export for inter-process transfer.
GSSCredential represents GSS-API credentials and may contain multiple mechanism-specific credential elements. It provides getName, getRemainingLifetime, getUsage, getMechs, and add methods; the interface implements Cloneable.
GSSException extends Exception and signals fatal GSS-API errors via major status codes (BAD_BINDINGS=1 through NAME_NOT_MN=18, and DUPLICATE_TOKEN=19 through GAP_TOKEN=22) and mechanism-specific minor codes. A new getOutputToken() method (added by RFC 8353) returns an optional error token to send to the peer.
GSSManager is an abstract factory class that instantiates GSSName, GSSCredential, and GSSContext objects, and provides mechanism query methods (getMechs, getNamesForMech, getMechsForName). A default instance is obtained via getInstance(); subclasses may be provided for custom implementations.
GSSName represents principal identities and may contain multiple names from different namespaces referring to the same entity. Key operations are equals (name comparison), canonicalize (convert to mechanism name), export (produce byte-array MN form importable as NT_EXPORT_NAME), and toString.
MessageProp is a helper class passed into per-message calls (wrap, unwrap, getMIC, verifyMIC) to convey QOP, privacy (confidentiality) settings, and supplementary status: isDuplicateToken, isOldToken, isUnseqToken, isGapToken.
The Oid class represents ASN.1 Object Identifiers in immutable form, constructable from dot-notation strings (e.g., '1.3.6.1.5.6.2') or DER encoding. Its immutability allows safe sharing across threads. The containedIn method implements gss_test_oid_set_member.
Inter-process tokens exported via GSSContext.export() may contain sensitive security context data including cryptographic session keys. Applications must ensure these tokens are transmitted only to trustworthy processes and protected against interception during transfer.
The new output token returned by GSSException.getOutputToken() when initSecContext or acceptSecContext fail may contain mechanism-specific diagnostic information. Implementations and applications should consider whether transmitting this error token to the peer could leak sensitive information about the failure cause.
GSS-API usage follows four stages: (1) credential acquisition, where the application obtains credentials proving its identity; (2) security context establishment between peers using initSecContext/acceptSecContext; (3) per-message protection using getMIC/wrap/verifyMIC/unwrap; (4) context invalidation via dispose to release cryptographic resources.