rocks.xmpp.core.sasl

Class AuthenticationManager

java.lang.Object

rocks.xmpp.core.stream.FeatureNegotiator

rocks.xmpp.core.sasl.AuthenticationManager

public final class AuthenticationManager
extends FeatureNegotiator

Manages SASL authentication as described in SASL Negotiation.

Author:

Christian Schudt

Nested Class Summary

Nested classes/interfaces inherited from class rocks.xmpp.core.stream.FeatureNegotiator

FeatureNegotiator.Status

Constructor Summary

Constructors

Constructor and Description
AuthenticationManager(XmppSession xmppSession, Lock lock) Creates the authentication manager.

Method Summary

Modifier and Type	Method and Description
void	authenticate(String authorizationId, String user, String password, CallbackHandler callbackHandler) Authenticates a user by choosing the "best" SASL mechanism available to both client and server.
void	authenticateAnonymously() Authenticates anonymously, if the server supports anonymous authentication.
boolean	canProcess(Object element) Checks, whether the element can be processed by the feature negotiator.
LinkedHashSet<String>	getPreferredMechanisms() Gets the preferred mechanisms used for this connection.
boolean	needsRestart() Checks, if the feature needs a stream restart after it has been successfully negotiated.
FeatureNegotiator.Status	processNegotiation(Object element) Processes a feature protocol element or the feature element itself.
void	reAuthenticate() Re-authenticates after a connection has disconnected and reconnected.
void	setPreferredMechanisms(LinkedHashSet<String> preferredMechanisms) Sets the preferred mechanisms used for this connection.

Methods inherited from class rocks.xmpp.core.stream.FeatureNegotiator

addFeatureListener, getFeatureClass, notifyFeatureNegotiated, removeFeatureListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AuthenticationManager

public AuthenticationManager(XmppSession xmppSession,
                             Lock lock)

Creates the authentication manager. Usually only the XmppSession should create it implicitly.

Parameters:

xmppSession - The connection.

lock - The lock object, which is used to make the current thread wait during authentication.

Method Detail

getPreferredMechanisms

public LinkedHashSet<String> getPreferredMechanisms()

Gets the preferred mechanisms used for this connection.

Returns:

The preferred mechanisms.

See Also:

setPreferredMechanisms(java.util.LinkedHashSet)

setPreferredMechanisms

public void setPreferredMechanisms(LinkedHashSet<String> preferredMechanisms)

Sets the preferred mechanisms used for this connection.

6.3.3. Mechanism Preferences

Any entity that will act as a SASL client or a SASL server MUST maintain an ordered list of its preferred SASL mechanisms according to the client or server, where the list is ordered according to local policy or user configuration (which SHOULD be in order of perceived strength to enable the strongest authentication possible). The initiating entity MUST maintain its own preference order independent of the preference order of the receiving entity. A client MUST try SASL mechanisms in its preference order. For example, if the server offers the ordered list "PLAIN SCRAM-SHA-1 GSSAPI" or "SCRAM-SHA-1 GSSAPI PLAIN" but the client's ordered list is "GSSAPI SCRAM-SHA-1", the client MUST try GSSAPI first and then SCRAM-SHA-1 but MUST NOT try PLAIN (since PLAIN is not on its list).

Parameters:

preferredMechanisms - The preferred mechanisms.

See Also:

getPreferredMechanisms()

authenticate

public void authenticate(String authorizationId,
                         String user,
                         String password,
                         CallbackHandler callbackHandler)
                  throws LoginException,
                         SaslException

Authenticates a user by choosing the "best" SASL mechanism available to both client and server.

Parameters:

authorizationId - The authorization identity.

6.3.8. Authorization Identity

An authorization identity is an OPTIONAL identity included by the initiating entity to specify an identity to act as (see Section 2 of [SASL]). In client-to-server streams, it would most likely be used by an administrator to perform some management task on behalf of another user, whereas in server-to-server streams it would most likely be used to specify a particular add-on service at an XMPP service (e.g., a multi-user chat server at conference.example.com that is hosted by the example.com XMPP service). If the initiating entity wishes to act on behalf of another entity and the selected SASL mechanism supports transmission of an authorization identity, the initiating entity MUST provide an authorization identity during SASL negotiation. If the initiating entity does not wish to act on behalf of another entity, it MUST NOT provide an authorization identity.

In the case of client-to-server communication, the value of an authorization identity MUST be a bare JID (<localpart@domainpart>) rather than a full JID (<localpart@domainpart/resourcepart>).

user - The user.

6.3.7. Simple User Name

Some SASL mechanisms (e.g., CRAM-MD5, DIGEST-MD5, and SCRAM) specify that the authentication identity used in the context of such mechanisms is a "simple user name" (see Section 2 of [SASL] as well as [SASLPREP]). The exact form of the simple user name in any particular mechanism or deployment thereof is a local matter, and a simple user name does not necessarily map to an application identifier such as a JID or JID component (e.g., a localpart). However, in the absence of local information provided by the server, an XMPP client SHOULD assume that the authentication identity for such a SASL mechanism is a simple user name equal to the localpart of the user's JID.

password - The user's password.

callbackHandler - An optional callback handler. Should be null in most cases.

Throws:

SaslException - If a SaslClient could not be created.

LoginException - If the login failed, due to a SASL error reported by the server.

FailedLoginException - If the login failed, due to a wrong username or password. It is thrown if the server reports a <not-authorized/> SASL error.

AccountLockedException - If the login failed, because the account has been disabled. It is thrown if the server reports a <account-disabled/> SASL error.

CredentialExpiredException - If the login failed, because the credentials have expired. It is thrown if the server reports a <credentials-expired/> SASL error.

authenticateAnonymously

public void authenticateAnonymously()
                             throws LoginException

Authenticates anonymously, if the server supports anonymous authentication.

Throws:

LoginException - If the anonymous login failed. See authenticate(String, String, String, javax.security.auth.callback.CallbackHandler) for more a detailed description.

reAuthenticate

public void reAuthenticate()
                    throws SaslException,
                           LoginException

Re-authenticates after a connection has disconnected and reconnected. The parameters from the last authentication process is used to re-authenticate.

Throws:

SaslException - If the SASL mechanism could not be created.

LoginException - If the login failed.

processNegotiation

public FeatureNegotiator.Status processNegotiation(Object element)
                                            throws Exception

Description copied from class: FeatureNegotiator

Processes a feature protocol element or the feature element itself.

Specified by:

processNegotiation in class FeatureNegotiator

Parameters:

element - The XML element, which belongs to the feature negotiation, e.g. <challenge/> for SASL negotiation or the feature element itself, e.g. <mechanisms/>.

Returns:

The status of the feature negotiation.

Throws:

Exception - Any exception which might be thrown during a feature negotiation. Note that any exception thrown during the feature negotiation process is thrown by the XmppSession.connect() method and therefore will abort the connection process.

needsRestart

public boolean needsRestart()

Description copied from class: FeatureNegotiator

Checks, if the feature needs a stream restart after it has been successfully negotiated. Override this method (returning true), if the feature requires a stream restart after negotiation.

By default this method returns false.

Overrides:

needsRestart in class FeatureNegotiator

Returns:

True, if the stream requires a restart after feature negotiation.

canProcess

public boolean canProcess(Object element)

Description copied from class: FeatureNegotiator

Checks, whether the element can be processed by the feature negotiator.

Specified by:

canProcess in class FeatureNegotiator

Parameters:

element - The feature protocol element, e.g. <challenge/>. The element is never the feature element itself, e.g. <mechanisms/>, which is advertised in the <stream:features/> element.

Returns:

True, if the element can be processed by the feature negotiator.