SASLMechanism (jamppa 0.1.1 API)

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

All Implemented Interfaces:

CallbackHandler

Direct Known Subclasses:

SASLAnonymous, SASLCramMD5Mechanism, SASLDigestMD5Mechanism, SASLExternalMechanism, SASLGSSAPIMechanism, SASLPlainMechanism
```
public abstract class SASLMechanism
extends Object
implements 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

Nested Classes
Modifier and Type	Class and Description
`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

Fields
Modifier and Type Field and Description

protected String authenticationId

protected String hostname

protected String password

protected SaslClient sc

Fields
Modifier and Type	Field and Description
`protected String`	`authenticationId`
`protected String`	`hostname`
`protected String`	`password`
`protected SaslClient`	`sc`

Constructor Summary

Constructors
Constructor and Description

SASLMechanism(SASLAuthentication saslAuthentication)

Constructors
Constructor and Description
`SASLMechanism(SASLAuthentication saslAuthentication)`

Method Summary

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

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - sc
```
protected SaslClient sc
```
  - authenticationId
```
protected String authenticationId
```
  - password
```
protected String password
```
  - hostname
```
protected String hostname
```
- Constructor Detail
  - SASLMechanism
```
public SASLMechanism(SASLAuthentication saslAuthentication)
```
- Method Detail
  - authenticate
```
public void authenticate(String username,
                String host,
                String serviceName,
                String password)
                  throws 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:
    
    IOException - If a network error occurs while authenticating.
    
    XMPPException - If a protocol error occurs or the user is not authenticated.
  - authenticate
```
public void authenticate(String username,
                String host,
                String password)
                  throws 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:
    
    IOException - If a network error occurs while authenticating.
    
    XMPPException - If a protocol error occurs or the user is not authenticated.
  - authenticate
```
public void authenticate(String username,
                String host,
                CallbackHandler cbh)
                  throws 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:
    
    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 IOException,
                            XMPPException
```
    Throws:
    
    IOException
    
    XMPPException
  - challengeReceived
```
public void challengeReceived(String challenge)
                       throws 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:
    
    IOException - if an exception sending the response occurs.
  - getName
```
protected abstract 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(Callback[] callbacks)
            throws IOException,
                   UnsupportedCallbackException
```
    Specified by:
    
    handle in interface CallbackHandler
    
    Throws:
    
    IOException
    
    UnsupportedCallbackException

Class SASLMechanism

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

sc

authenticationId

password

hostname

Constructor Detail

SASLMechanism

Method Detail

authenticate

authenticate

authenticate

authenticate

challengeReceived

getName

getSASLAuthentication

handle