Overview
The Java Generic Security Services API (JGSS) provides a framework for applications to perform secure authentication and communication using security services like Kerberos v5. The API is based on the IETF GSS-API specification defined in RFC 2743 and RFC 2744. Key features include:- Authentication: Mutual authentication between client and server
- Message Protection: Integrity and confidentiality for messages
- Credential Delegation: Forward credentials to enable multi-tier authentication
- Mechanism Independence: Pluggable security mechanisms (primarily Kerberos v5)
org.ietf.jgss package.
Core Classes
GSSManager
Factory class for creating GSS-API objects. Entry point for the GSS-API.Returns the default GSSManager implementation.
Factory method to convert a string name to a GSSName object.Common name types:
GSSName.NT_USER_NAME- Username formatGSSName.NT_HOSTBASED_SERVICE- Service name format (e.g., “service@host”)GSSName.NT_EXPORT_NAME- Exported name format
GSSException- if the name cannot be created
Factory method for acquiring a single mechanism credential.Parameters:
name- Principal name (use null for default)lifetime- Lifetime in seconds (useGSSCredential.DEFAULT_LIFETIMEorINDEFINITE_LIFETIME)mech- Mechanism OID (use null for default)usage-INITIATE_ONLY,ACCEPT_ONLY, orINITIATE_AND_ACCEPT
GSSException- if credential cannot be acquired
Factory method for creating a context on the initiator’s side.Returns: An unestablished GSSContext
Factory method for creating a context on the acceptor’s side.Returns: An unestablished GSSContext
GSSContext
Encapsulates a GSS-API security context for authentication and secure communication.Called by the context initiator to start the context creation. Returns a token to send to the peer, or null.Throws:
GSSException- if context initialization fails
Called by the context acceptor to process a token from the peer. Returns a token to send to the peer, or null.Throws:
GSSException- if context acceptance fails
Returns true if this is a fully established context and no more tokens are needed from the peer.
Applies per-message security services (encryption and/or integrity) over the established context.Parameters:
inBuf- Application data to protectoffset- Offset within inBuf where data beginslen- Length of datamsgProp- MessageProp specifying QOP and privacy requirements
GSSException- if the operation fails
Processes tokens generated by wrap() on the other side. Verifies the MIC and decrypts if privacy was applied.Returns: The unwrapped messageThrows:
GSSException- if verification or decryption fails
Returns a token containing a cryptographic Message Integrity Code (MIC) for the supplied message.Returns: Token containing the MIC
verifyMIC(byte[] inToken, int tokOffset, int tokLen, byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp)
void
Verifies the cryptographic MIC contained in the token over the supplied message.Throws:
GSSException- if verification fails
Releases system resources and cryptographic information stored in the context.
Context Configuration Methods
Requests mutual authentication during context establishment. Must be called before initSecContext().
Requests confidentiality (encryption) service. Must be called before initSecContext().
Requests integrity protection service. Must be called before initSecContext().
Requests credential delegation. Must be called before initSecContext().
Requests replay detection for per-message security services.
Requests sequence checking for per-message security services.
Query Methods
Returns true if mutual authentication is enabled.
Returns true if confidentiality service is available.
Returns true if integrity service is available.
Returns true if credentials were delegated.
Returns the name of the context initiator.
Returns the name of the context acceptor.
Returns the remaining lifetime of the context in seconds.
GSSCredential
Encapsulates GSS-API credentials for a principal.GSSCredential Usage
Returns the name of the principal associated with this credential.
Returns the remaining lifetime in seconds for this credential.
Returns the usage mode for this credential:
INITIATE_ONLY, ACCEPT_ONLY, or INITIATE_AND_ACCEPT.GSSName
Represents a GSS-API principal entity.GSSName Operations
Complete Example
MessageProp
Used to specify and retrieve per-message properties.MessageProp Usage
Exception Handling
- GSSException
- Common Error Codes
All JGSS methods throw GSSException. Major error codes include:
The default GSSManager instance always supports the Kerberos v5 mechanism (OID: 1.2.840.113554.1.2.2) as defined in RFC 1964.
See Also
- java.security Package - Core security framework
- Cryptography APIs - Encryption and key management
- RFC 2743: Generic Security Service API Version 2
- RFC 2744: Generic Security Service API Version 2: C-bindings
- RFC 1964: Kerberos Version 5 GSS-API Mechanism