Package org.jivesoftware.smack.sasl

Class SASLMechanism

java.lang.Object

org.jivesoftware.smack.sasl.SASLMechanism

All Implemented Interfaces:

java.lang.Comparable<SASLMechanism>

Direct Known Subclasses:

SASLAnonymous, SASLDigestMD5Mechanism, SASLExternalMechanism, SASLJavaXMechanism, SASLPlainMechanism, SASLXOauth2Mechanism, ScramMechanism

public abstract class SASLMechanism
extends java.lang.Object
implements java.lang.Comparable<SASLMechanism>

Base class for SASL mechanisms. Subclasses will likely want to implement their own versions of these methods:

• authenticate(String, String, DomainBareJid, String, EntityBareJid, SSLSession) -- Initiate authentication stanza using the deprecated method.
• authenticate(String, DomainBareJid, CallbackHandler, EntityBareJid, SSLSession) -- Initiate authentication stanza using the CallbackHandler method.
• challengeReceived(String, boolean) -- Handle a challenge from the server.

Field Summary

Fields

Modifier and Type	Field	Description
protected java.lang.String	authenticationId	Then authentication identity (authcid).
protected EntityBareJid	authorizationId	The authorization identifier (authzid).
protected XMPPConnection	connection
protected ConnectionConfiguration	connectionConfiguration
static java.lang.String	CRAMMD5
static java.lang.String	DIGESTMD5
static java.lang.String	EXTERNAL
static java.lang.String	GSSAPI
protected java.lang.String	host
protected java.lang.String	password	The users password
static java.lang.String	PLAIN
protected DomainBareJid	serviceName	The name of the XMPP service
protected javax.net.ssl.SSLSession	sslSession	The used SSL/TLS session (if any).

Constructor Summary

Constructors

Constructor	Description
SASLMechanism()

Method Summary

Modifier and Type	Method	Description
void	afterFinalSaslChallenge()	Check if the SASL mechanism was successful and if it was, then mark it so.
void	authenticate(java.lang.String username, java.lang.String host, DomainBareJid serviceName, java.lang.String password, EntityBareJid authzid, javax.net.ssl.SSLSession sslSession)	Builds and sends the auth stanza to the server.
void	authenticate(java.lang.String host, DomainBareJid serviceName, javax.security.auth.callback.CallbackHandler cbh, EntityBareJid authzid, javax.net.ssl.SSLSession sslSession)	Builds and sends the auth stanza to the server.
protected void	authenticateInternal()
protected abstract void	authenticateInternal(javax.security.auth.callback.CallbackHandler cbh)
boolean	authzidSupported()
void	challengeReceived(java.lang.String challengeString, boolean finalChallenge)	The server is challenging the SASL mechanism for the stanza he just sent.
protected abstract void	checkIfSuccessfulOrThrow()
int	compareTo(SASLMechanism other)
protected byte[]	evaluateChallenge(byte[] challenge)	Evaluate the SASL challenge.
protected abstract byte[]	getAuthenticationText()	Should return the initial response of the SASL mechanism.
abstract java.lang.String	getName()	Returns the common name of the SASL mechanism.
abstract int	getPriority()	Get the priority of this SASL mechanism.
SASLMechanism	instanceForAuthentication(XMPPConnection connection, ConnectionConfiguration connectionConfiguration)
boolean	isAuthenticationSuccessful()
boolean	isFinished()
protected abstract SASLMechanism	newInstance()
boolean	requiresPassword()
protected static java.lang.String	saslPrep(java.lang.String string)	SASLprep the given String.
void	setException(java.lang.Exception exception)
void	throwExceptionIfRequired()
protected static byte[]	toBytes(java.lang.String string)
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

CRAMMD5

public static final java.lang.String CRAMMD5

See Also:

Constant Field Values

DIGESTMD5

public static final java.lang.String DIGESTMD5

See Also:

Constant Field Values

EXTERNAL

public static final java.lang.String EXTERNAL

See Also:

Constant Field Values

GSSAPI

public static final java.lang.String GSSAPI

See Also:

Constant Field Values

PLAIN

public static final java.lang.String PLAIN

See Also:

Constant Field Values

connection

protected XMPPConnection connection

connectionConfiguration

protected ConnectionConfiguration connectionConfiguration

authenticationId

protected java.lang.String authenticationId

Then authentication identity (authcid). RFC 6120 § 6.3.7 informs us that some SASL mechanisms use this as a "simple user name". But the exact form is a matter of the mechanism and that it does not necessarily map to an localpart. But it usually is the localpart of the client JID, although sometimes other formats are used (e.g. the full JID).

Not to be confused with the authzid (see RFC 6120 § 6.3.8).

authorizationId

protected EntityBareJid authorizationId

The authorization identifier (authzid). This is always a bare Jid, but can be null.

serviceName

protected DomainBareJid serviceName

The name of the XMPP service

password

protected java.lang.String password

The users password

host

protected java.lang.String host

sslSession

protected javax.net.ssl.SSLSession sslSession

The used SSL/TLS session (if any).

Constructor Detail

SASLMechanism

public SASLMechanism()

Method Detail

authenticate

public final void authenticate(java.lang.String username,
                               java.lang.String host,
                               DomainBareJid serviceName,
                               java.lang.String password,
                               EntityBareJid authzid,
                               javax.net.ssl.SSLSession sslSession)
                        throws SmackException.SmackSaslException,
                               SmackException.NotConnectedException,
                               java.lang.InterruptedException

Builds and sends the auth stanza to the server. Note that this method of authentication is not recommended, since it is very inflexible. Use authenticate(String, DomainBareJid, CallbackHandler, EntityBareJid, SSLSession) whenever possible. Explanation of auth stanza: The client authentication stanza needs to include the digest-uri of the form: xmpp/serviceName 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.

authzid - the optional authorization identity.

sslSession - the optional SSL/TLS session (if one was established)

Throws:

SmackException.SmackSaslException - if a SASL related error occurs.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

authenticateInternal

protected void authenticateInternal()
                             throws SmackException.SmackSaslException

Throws:

SmackException.SmackSaslException

authenticate

public void authenticate(java.lang.String host,
                         DomainBareJid serviceName,
                         javax.security.auth.callback.CallbackHandler cbh,
                         EntityBareJid authzid,
                         javax.net.ssl.SSLSession sslSession)
                  throws SmackException.SmackSaslException,
                         SmackException.NotConnectedException,
                         java.lang.InterruptedException

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:

host - the hostname where the user account resides.

serviceName - the xmpp service location

cbh - the CallbackHandler to obtain user information.

authzid - the optional authorization identity.

sslSession - the optional SSL/TLS session (if one was established)

Throws:

SmackException.SmackSaslException - if a SASL related error occurs.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

authenticateInternal

protected abstract void authenticateInternal(javax.security.auth.callback.CallbackHandler cbh)
                                      throws SmackException.SmackSaslException

Throws:

SmackException.SmackSaslException

getAuthenticationText

protected abstract byte[] getAuthenticationText()
                                         throws SmackException.SmackSaslException

Should return the initial response of the SASL mechanism. The returned byte array will be send base64 encoded to the server. SASL mechanism are free to return null or an empty array here.

Returns:

the initial response or null

Throws:

SmackException.SmackSaslException - if a SASL specific error occurred.

challengeReceived

public final void challengeReceived(java.lang.String challengeString,
                                    boolean finalChallenge)
                             throws SmackException.SmackSaslException,
                                    java.lang.InterruptedException,
                                    SmackException.NotConnectedException

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

Parameters:

challengeString - a base64 encoded string representing the challenge.

finalChallenge - true if this is the last challenge send by the server within the success stanza

Throws:

SmackException.SmackSaslException - if a SASL related error occurs.

java.lang.InterruptedException - if the connection is interrupted

SmackException.NotConnectedException - if the XMPP connection is not connected.

evaluateChallenge

protected byte[] evaluateChallenge(byte[] challenge)
                            throws SmackException.SmackSaslException

Evaluate the SASL challenge.

Parameters:

challenge - challenge to evaluate.

Returns:

null.

Throws:

SmackException.SmackSaslException - If a SASL related error occurs.

compareTo

public final int compareTo(SASLMechanism other)

Specified by:

compareTo in interface java.lang.Comparable<SASLMechanism>

getName

public 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.

getPriority

public abstract int getPriority()

Get the priority of this SASL mechanism. Lower values mean higher priority.

Returns:

the priority of this SASL mechanism.

afterFinalSaslChallenge

public final void afterFinalSaslChallenge()
                                   throws SmackException.SmackSaslException

Check if the SASL mechanism was successful and if it was, then mark it so.

Throws:

SmackException.SmackSaslException - in case of an SASL error.

checkIfSuccessfulOrThrow

protected abstract void checkIfSuccessfulOrThrow()
                                          throws SmackException.SmackSaslException

Throws:

SmackException.SmackSaslException

instanceForAuthentication

public SASLMechanism instanceForAuthentication(XMPPConnection connection,
                                               ConnectionConfiguration connectionConfiguration)

authzidSupported

public boolean authzidSupported()

requiresPassword

public boolean requiresPassword()

isAuthenticationSuccessful

public boolean isAuthenticationSuccessful()

isFinished

public boolean isFinished()

throwExceptionIfRequired

public void throwExceptionIfRequired()
                              throws SmackException.SmackSaslException,
                                     SASLErrorException,
                                     SmackException.NotConnectedException,
                                     java.lang.InterruptedException,
                                     SmackException.NoResponseException

Throws:

SmackException.SmackSaslException

SASLErrorException

SmackException.NotConnectedException

java.lang.InterruptedException

SmackException.NoResponseException

setException

public void setException(java.lang.Exception exception)

newInstance

protected abstract SASLMechanism newInstance()

toBytes

protected static byte[] toBytes(java.lang.String string)

saslPrep

protected static java.lang.String saslPrep(java.lang.String string)

SASLprep the given String. The resulting String is in UTF-8.

Parameters:

string - the String to sasl prep.

Returns:

the given String SASL preped

See Also:

RFC 4013 - SASLprep: Stringprep Profile for User Names and Passwords

toString

public final java.lang.String toString()

Overrides:

toString in class java.lang.Object