org.jivesoftware.smack
Class SASLAuthentication

java.lang.Object
  org.jivesoftware.smack.SASLAuthentication

public class SASLAuthentication
extends Object

This class is responsible authenticating the user using SASL, binding the resource to the connection and establishing a session with the server.

Once TLS has been negotiated (i.e. the connection has been secured) it is possible to register with the server, authenticate using Non-SASL or authenticate using SASL. If the server supports SASL then Smack will first try to authenticate using SASL. But if that fails then Non-SASL will be tried.

The server may support many SASL mechanisms to use for authenticating. Out of the box Smack provides several SASL mechanisms, but it is possible to register new SASL Mechanisms. Use registerSASLMechanism(String, Class) to register a new mechanisms. A registered mechanism wont be used until supportSASLMechanism(String, int) is called. By default, the list of supported SASL mechanisms is determined from the SmackConfiguration.

Once the user has been authenticated with SASL, it is necessary to bind a resource for the connection. If no resource is passed in authenticate(String, String, String) then the server will assign a resource for the connection. In case a resource is passed then the server will receive the desired resource but may assign a modified resource for the connection.

Once a resource has been binded and if the server supports sessions then Smack will establish a session so that instant messaging and presence functionalities may be used.

Author:

Gaston Dombiak, Jay Kline

See Also:

SASLMechanism

Method Summary

String	authenticate(String username, String resource, javax.security.auth.callback.CallbackHandler cbh) Performs SASL authentication of the specified user.
String	authenticate(String username, String password, String resource) Performs SASL authentication of the specified user.
String	authenticateAnonymously() Performs ANONYMOUS SASL authentication.
static List<Class>	getRegisterSASLMechanisms() Returns the registerd SASLMechanism classes sorted by the level of preference.
boolean	hasAnonymousAuthentication() Returns true if the server offered ANONYMOUS SASL as a way to authenticate users.
boolean	hasNonAnonymousAuthentication() Returns true if the server offered SASL authentication besides ANONYMOUS SASL.
protected void	init() Initializes the internal state in order to be able to be reused.
boolean	isAuthenticated() Returns true if the user was able to authenticate with the server usins SASL.
static void	registerSASLMechanism(String name, Class mClass) Registers a new SASL mechanism
void	send(String stanza)
static void	supportSASLMechanism(String name) Registers a new SASL mechanism in the specified preference position.
static void	supportSASLMechanism(String name, int index) Registers a new SASL mechanism in the specified preference position.
static void	unregisterSASLMechanism(String name) Unregisters an existing SASL mechanism.
static void	unsupportSASLMechanism(String name) Un-supports an existing SASL mechanism.

Methods inherited from class java.lang.Object

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

Method Detail

registerSASLMechanism

public static void registerSASLMechanism(String name,
                                         Class mClass)

Registers a new SASL mechanism

Parameters:

name - common name of the SASL mechanism. E.g.: PLAIN, DIGEST-MD5 or KERBEROS_V4.

mClass - a SASLMechanism subclass.

unregisterSASLMechanism

public static void unregisterSASLMechanism(String name)

Unregisters an existing SASL mechanism. Once the mechanism has been unregistered it won't be possible to authenticate users using the removed SASL mechanism. It also removes the mechanism from the supported list.

Parameters:

name - common name of the SASL mechanism. E.g.: PLAIN, DIGEST-MD5 or KERBEROS_V4.

supportSASLMechanism

public static void supportSASLMechanism(String name)

Registers a new SASL mechanism in the specified preference position. The client will try to authenticate using the most prefered SASL mechanism that is also supported by the server. The SASL mechanism must be registered via registerSASLMechanism(String, Class)

Parameters:

name - common name of the SASL mechanism. E.g.: PLAIN, DIGEST-MD5 or KERBEROS_V4.

supportSASLMechanism

public static void supportSASLMechanism(String name,
                                        int index)

Registers a new SASL mechanism in the specified preference position. The client will try to authenticate using the most prefered SASL mechanism that is also supported by the server. Use the index parameter to set the level of preference of the new SASL mechanism. A value of 0 means that the mechanism is the most prefered one. The SASL mechanism must be registered via registerSASLMechanism(String, Class)

Parameters:

name - common name of the SASL mechanism. E.g.: PLAIN, DIGEST-MD5 or KERBEROS_V4.

index - preference position amongst all the implemented SASL mechanism. Starts with 0.

unsupportSASLMechanism

public static void unsupportSASLMechanism(String name)

Un-supports an existing SASL mechanism. Once the mechanism has been unregistered it won't be possible to authenticate users using the removed SASL mechanism. Note that the mechanism is still registered, but will just not be used.

Parameters:

name - common name of the SASL mechanism. E.g.: PLAIN, DIGEST-MD5 or KERBEROS_V4.

getRegisterSASLMechanisms

public static List<Class> getRegisterSASLMechanisms()

Returns the registerd SASLMechanism classes sorted by the level of preference.

Returns:

the registerd SASLMechanism classes sorted by the level of preference.

hasAnonymousAuthentication

public boolean hasAnonymousAuthentication()

Returns true if the server offered ANONYMOUS SASL as a way to authenticate users.

Returns:

true if the server offered ANONYMOUS SASL as a way to authenticate users.

hasNonAnonymousAuthentication

public boolean hasNonAnonymousAuthentication()

Returns true if the server offered SASL authentication besides ANONYMOUS SASL.

Returns:

true if the server offered SASL authentication besides ANONYMOUS SASL.

authenticate

public String authenticate(String username,
                           String resource,
                           javax.security.auth.callback.CallbackHandler cbh)
                    throws XMPPException

Performs SASL authentication of the specified user. If SASL authentication was successful then resource binding and session establishment will be performed. This method will return the full JID provided by the server while binding a resource to the connection.

The server may assign a full JID with a username or resource different than the requested by this method.

Parameters:

username - the username that is authenticating with the server.

resource - the desired resource.

cbh - the CallbackHandler used to get information from the user

Returns:

the full JID provided by the server while binding a resource to the connection.

Throws:

XMPPException - if an error occures while authenticating.

authenticate

public String authenticate(String username,
                           String password,
                           String resource)
                    throws XMPPException

Performs SASL authentication of the specified user. If SASL authentication was successful then resource binding and session establishment will be performed. This method will return the full JID provided by the server while binding a resource to the connection.

The server may assign a full JID with a username or resource different than the requested by this method.

Parameters:

username - the username that is authenticating with the server.

password - the password to send to the server.

resource - the desired resource.

Returns:

the full JID provided by the server while binding a resource to the connection.

Throws:

XMPPException - if an error occures while authenticating.

authenticateAnonymously

public String authenticateAnonymously()
                               throws XMPPException

Performs ANONYMOUS SASL authentication. If SASL authentication was successful then resource binding and session establishment will be performed. This method will return the full JID provided by the server while binding a resource to the connection.

The server will assign a full JID with a randomly generated resource and possibly with no username.

Returns:

the full JID provided by the server while binding a resource to the connection.

Throws:

XMPPException - if an error occures while authenticating.

isAuthenticated

public boolean isAuthenticated()

Returns true if the user was able to authenticate with the server usins SASL.

Returns:

true if the user was able to authenticate with the server usins SASL.

send

public void send(String stanza)
          throws IOException

Throws:

IOException

init

protected void init()

Initializes the internal state in order to be able to be reused. The authentication is used by the connection at the first login and then reused after the connection is disconnected and then reconnected.