org.jivesoftware.smack.sasl
Class SASLMechanism

java.lang.Object
  org.jivesoftware.smack.sasl.SASLMechanism

All Implemented Interfaces:

javax.security.auth.callback.CallbackHandler

Direct Known Subclasses:

SASLAnonymous, SASLCramMD5Mechanism, SASLDigestMD5Mechanism, SASLExternalMechanism, SASLGSSAPIMechanism, SASLPlainMechanism

public abstract class SASLMechanism
extends java.lang.Object
implements javax.security.auth.callback.CallbackHandler

Base class for SASL mechanisms. Subclasses must implement these methods:

• getName() -- returns the common name of the SASL mechanism.

Subclasses will likely want to implement their own versions of these mthods:

authenticate(String, String, String) -- Initiate authentication stanza using the deprecated method.

authenticate(String, String, CallbackHandler) -- Initiate authentication stanza using the CallbackHandler method.

challengeReceived(String) -- Handle a challenge from the server.

Basic XMPP SASL authentication steps: 1. Client authentication initialization, stanza sent to the server (Base64 encoded): 2. Server sends back to the client the challenge response (Base64 encoded) sample: realm=,nonce="OA6MG9tEQGm2hh",qop="auth",charset=utf-8,algorithm=md5-sess 3. The client responds back to the server (Base 64 encoded): sample: username=,realm=,nonce="OA6MG9tEQGm2hh", cnonce="OA6MHXh6VqTrRk",nc=00000001,qop=auth, digest-uri=, response=d388dad90d4bbd760a152321f2143af7, charset=utf-8, authzid= 4. The server evaluates if the user is present and contained in the REALM if successful it sends: (Base64 encoded) if not successful it sends: sample: cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZmZmZA==

Author:

Jay Kline

Nested Class Summary

class	SASLMechanism.AuthMechanism Initiating SASL authentication by select a mechanism.
static class	SASLMechanism.Challenge A SASL challenge stanza.
static class	SASLMechanism.Failure A SASL failure stanza.
class	SASLMechanism.Response A SASL response stanza.
static class	SASLMechanism.Success A SASL success stanza.

Field Summary

protected java.lang.String	authenticationId
protected java.lang.String	hostname
protected java.lang.String	password
protected javax.security.sasl.SaslClient	sc

Constructor Summary

SASLMechanism(SASLAuthentication saslAuthentication)

Method Summary

protected void	authenticate()
void	authenticate(java.lang.String username, java.lang.String host, javax.security.auth.callback.CallbackHandler cbh) Builds and sends the auth stanza to the server.
void	authenticate(java.lang.String username, java.lang.String host, java.lang.String password) Deprecated. Please use authenticate(String, String, String, String) instead.
void	authenticate(java.lang.String username, java.lang.String host, java.lang.String serviceName, java.lang.String password) Builds and sends the auth stanza to the server.
void	challengeReceived(java.lang.String challenge) The server is challenging the SASL mechanism for the stanza he just sent.
protected abstract java.lang.String	getName() Returns the common name of the SASL mechanism.
protected SASLAuthentication	getSASLAuthentication()
void	handle(javax.security.auth.callback.Callback[] callbacks)

Methods inherited from class java.lang.Object

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

Field Detail

sc

protected javax.security.sasl.SaslClient sc

authenticationId

protected java.lang.String authenticationId

password

protected java.lang.String password

hostname

protected java.lang.String hostname

Constructor Detail

SASLMechanism

public SASLMechanism(SASLAuthentication saslAuthentication)

Method Detail

authenticate

public void authenticate(java.lang.String username,
                         java.lang.String host,
                         java.lang.String serviceName,
                         java.lang.String password)
                  throws java.io.IOException,
                         XMPPException

Builds and sends the auth stanza to the server. Note that this method of authentication is not recommended, since it is very inflexable. Use authenticate(String, String, CallbackHandler) whenever possible. Explanation of auth stanza: The client authentication stanza needs to include the digest-uri of the form: xmpp/serverName From RFC-2831: digest-uri = "digest-uri" "=" digest-uri-value digest-uri-value = serv-type "/" host [ "/" serv-name ] digest-uri: Indicates the principal name of the service with which the client wishes to connect, formed from the serv-type, host, and serv-name. For example, the FTP service on "ftp.example.com" would have a "digest-uri" value of "ftp/ftp.example.com"; the SMTP server from the example above would have a "digest-uri" value of "smtp/mail3.example.com/example.com". host: The DNS host name or IP address for the service requested. The DNS host name must be the fully-qualified canonical name of the host. The DNS host name is the preferred form; see notes on server processing of the digest-uri. serv-name: Indicates the name of the service if it is replicated. The service is considered to be replicated if the client's service-location process involves resolution using standard DNS lookup operations, and if these operations involve DNS records (such as SRV, or MX) which resolve one DNS name into a set of other DNS names. In this case, the initial name used by the client is the "serv-name", and the final name is the "host" component. For example, the incoming mail service for "example.com" may be replicated through the use of MX records stored in the DNS, one of which points at an SMTP server called "mail3.example.com"; it's "serv-name" would be "example.com", it's "host" would be "mail3.example.com". If the service is not replicated, or the serv-name is identical to the host, then the serv-name component MUST be omitted digest-uri verification is needed for ejabberd 2.0.3 and higher

Parameters:

username - the username of the user being authenticated.

host - the hostname where the user account resides.

serviceName - the xmpp service location - used by the SASL client in digest-uri creation serviceName format is: host [ "/" serv-name ] as per RFC-2831

password - the password for this account.

Throws:

java.io.IOException - If a network error occurs while authenticating.

XMPPException - If a protocol error occurs or the user is not authenticated.

authenticate

public void authenticate(java.lang.String username,
                         java.lang.String host,
                         java.lang.String password)
                  throws java.io.IOException,
                         XMPPException

Deprecated. Please use authenticate(String, String, String, String) instead.

Same as authenticate(String, String, String, String), but with the hostname used as the serviceName.

Kept for backward compatibility only.

Parameters:

username - the username of the user being authenticated.

host - the hostname where the user account resides.

password - the password for this account.

Throws:

java.io.IOException - If a network error occurs while authenticating.

XMPPException - If a protocol error occurs or the user is not authenticated.

authenticate

public void authenticate(java.lang.String username,
                         java.lang.String host,
                         javax.security.auth.callback.CallbackHandler cbh)
                  throws java.io.IOException,
                         XMPPException

Builds and sends the auth stanza to the server. The callback handler will handle any additional information, such as the authentication ID or realm, if it is needed.

Parameters:

username - the username of the user being authenticated.

host - the hostname where the user account resides.

cbh - the CallbackHandler to obtain user information.

Throws:

java.io.IOException - If a network error occures while authenticating.

XMPPException - If a protocol error occurs or the user is not authenticated.

authenticate

protected void authenticate()
                     throws java.io.IOException,
                            XMPPException

Throws:

java.io.IOException

XMPPException

challengeReceived

public void challengeReceived(java.lang.String challenge)
                       throws java.io.IOException

The server is challenging the SASL mechanism for the stanza he just sent. Send a response to the server's challenge.

Parameters:

challenge - a base64 encoded string representing the challenge.

Throws:

java.io.IOException - if an exception sending the response occurs.

getName

protected abstract java.lang.String getName()

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

Returns:

the common name of the SASL mechanism.

getSASLAuthentication

protected SASLAuthentication getSASLAuthentication()

handle

public void handle(javax.security.auth.callback.Callback[] callbacks)
            throws java.io.IOException,
                   javax.security.auth.callback.UnsupportedCallbackException

Specified by:

handle in interface javax.security.auth.callback.CallbackHandler

Throws:

java.io.IOException

javax.security.auth.callback.UnsupportedCallbackException