Generic Security Service API Version 2: Java Bindings Update
obsoleted by
- rfc-8353 — Generic Security Service API Version 2: Java Bindings Update
obsoletes
- rfc-2853 — Generic Security Service API Version 2 : Java Bindings
Extracted elements (30)
gss_process_context_token is intentionally excluded from the Java bindings, and gss_delete_sec_context is modified to not return peer tokens, in accordance with recommendations in RFC 2743. GSSContext.dispose() only destroys locally stored context information.
Java exceptions are used in place of the C-bindings major/minor status code return pattern for fatal errors. Supplementary non-fatal per-message status (duplicate, old, out-of-sequence, gap tokens) is returned via the MessageProp object rather than exceptions because exceptions are inappropriate for informational or warning-like conditions.
Java's automatic garbage collection eliminates the need for explicit release and duplication routines present in the C bindings. gss_release_name, gss_release_oid_set, gss_add_oid_set_member, gss_create_empty_oid_set, and gss_duplicate_name are all absent from the Java API.
Oid instances are intentionally immutable (no mutator methods) so they can be safely shared across threads and treated as statics without copying. A null value is accepted wherever a default OID is permitted.
The GSSContext.export() inter-process transfer mechanism is designed for the common server pattern of a parent accepting contexts and delegating them to child processes. After export the original GSSContext is invalidated; the adopting process reconstructs an equivalent context from the byte array token.
The GSSManager provider preference API (addProviderAtFront, addProviderAtEnd) is designed to be usable without knowledge of any specific SPI. The SPI specification is explicitly deferred; its existence is not mandatory for adoption of this API specification.
Applications may call isProtReady() on an incomplete GSSContext to determine whether per-message protection services (wrap, getMIC) are available before full context establishment completes. Some mechanisms embed sufficient key material in initial tokens to allow this optimization.
Applications that set channel bindings should either provide correct initiator and acceptor address information or omit the address fields entirely. Individual mechanisms may verify that address fields contain the correct host network address, making incorrect values a source of context-establishment failure.
All classes and interfaces for the Java GSS-API reside in the package 'org.ietf.jgss'. Applications that wish to make use of this API must import this package name.
Applications using inter-process tokens to transfer security contexts must take appropriate steps to protect these tokens in transit and transfer them only to trustworthy processes, as they may contain cryptographic keys and other sensitive data.
Default credential selection for a null GSSCredential is recommended: implementations should resolve a principal via platform network-identity, local-identity mapping, or user-configurable default in priority order, for both initiator and acceptor sides.
Delegation may only be provided at the explicit request of the application. If the application instructs the GSSContext object that delegation is not desired, the implementation must not permit delegation to occur, overriding any mechanism-specific delegation controls.
Platform providers of GSS are required not to add any constructors to the GSSManager class (private, public, or protected) to ensure all subclasses invoke only the default no-arg constructor provided by the compiler.
The printable form of an anonymous GSSName must be syntactically distinguishable from any valid principal name supported by the implementation, and the associated name-type OID must represent NT_ANONYMOUS. The printable form should imply anonymity (e.g., '<anonymous>') because it may appear in audit logs.
When a mechanism is incapable of providing a requested optional service, it is required to send at least one token from acceptor to initiator during context establishment so the initiating GSS-API can correctly indicate whether the service is supported by the acceptor.
When using the equals method of the GSSName interface and one of the operands represents an anonymous entity, the method must return 'false'.
ChannelBinding carries initiator and acceptor InetAddress values plus an application-supplied byte array. A MIC over the concatenated binding data is bound into the context-establishment token; mismatch causes acceptSecContext to throw GSSException with major code BAD_BINDINGS.
GSSContext encapsulates one end of a GSS-API security context including cryptographic state. It provides initSecContext/acceptSecContext for establishment, wrap/unwrap and getMIC/verifyMIC for per-message protection, export for inter-process transfer, and accessor methods for all context attributes.
GSSCredential (implements Cloneable) encapsulates multi-mechanism credentials for a single entity. It holds one credential element per mechanism, each with separate initiator and acceptor references, and must be released via dispose() after use.
GSSException replaces C-binding major/minor status codes. It carries one of 22 defined major status codes (BAD_BINDINGS=1 through GAP_TOKEN=22) and an optional mechanism-specific minor code. DUPLICATE_TOKEN, OLD_TOKEN, UNSEQ_TOKEN, and GAP_TOKEN are fatal only during context establishment; during per-message calls they appear as supplementary info in MessageProp.
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 the static getInstance() method; applications may also subclass GSSManager directly.
GSSName represents principal identities; a single internal GSSName may contain multiple mechanism-specific primitive names. Mechanism names (MNs) returned by GSSContext.getSrcName()/getTargName() contain exactly one primitive name and may be byte-compared after export via NT_EXPORT_NAME.
MessageProp is a helper class passed to per-message GSSContext operations. It conveys QOP level, the privacy (encryption) flag, an optional mechanism-specific minor status, and supplementary boolean states: isDuplicateToken, isOldToken, isUnseqToken, and isGapToken.
Oid is an immutable utility class representing ASN.1 OIDs identifying security mechanisms and name types. It may be constructed from dot-notation strings (e.g., '1.3.6.1.5.6.2') or DER encoding; getDER() returns the DER-encoded form for wire use.
Applications should not use confidential data as channel-binding components because some mechanisms include the actual channel binding data (not merely a MIC) in the context-establishment token, where it may be exposed to interceptors.
Inter-process tokens produced by GSSContext.export() may contain sensitive data including cryptographic keys. While GSS-API implementors are encouraged to avoid or cryptographically protect such content, many implementations cannot, so applications are solely responsible for protecting tokens in transit.
The GSS-API operational paradigm has four stages: (1) credential acquisition, (2) joint security context establishment via iterated initSecContext/acceptSecContext token exchange, (3) per-message protection services via wrap/getMIC and unwrap/verifyMIC on the established context, and (4) context invalidation and resource release via dispose().
All numeric values in the Java GSS-API are declared as Java 'int', guaranteed to be a 32-bit two's complement signed number. Boolean values use the Java 'boolean' primitive type throughout the API.
An exported name produced by GSSName.export() consists of a header containing an OID identifying the authenticating mechanism followed by a mechanism-specific name trailer whose syntax is defined by that mechanism. It may be re-imported via the byte-array GSSName constructor with NT_EXPORT_NAME as the name-type OID.
Authentication tokens are represented as Java byte arrays. Overloaded GSSContext methods also accept java.io InputStream/OutputStream pairs; callers must ensure streams will not block until a complete single token is available, as only one GSS-API token is processed per invocation.