gnu.javax.crypto.sasl

Class ClientMechanism

Implemented Interfaces:
SaslClient
Known Direct Subclasses:
AnonymousClient, CramMD5Client, PlainClient, SRPClient

public abstract class ClientMechanism
extends Object
implements SaslClient

A base class to facilitate implementing SASL client-side mechanisms.

Field Summary

protected String
authorizationID
The authorisation identity.
protected byte[]
channelBinding
Channel binding data to use with this mechanism instance.
protected boolean
complete
Whether authentication phase is completed (true) or not (false).
protected CallbackHandler
handler
Callback handler to use with this mechanism instance.
protected String
mechanism
Name of this mechanism.
protected Map<K,V>
properties
Properties of qualities desired for this mechanism.
protected String
protocol
Name of protocol using this mechanism.
protected String
serverName
Name of server to authenticate to.
protected int
state
The state of the authentication automaton.

Constructor Summary

ClientMechanism(String mechanism)

Method Summary

void
dispose()
Disposes of any system resources or security-sensitive information the SaslClient might be using.
protected byte[]
engineUnwrap(byte[] incoming, int offset, int len)
protected byte[]
engineWrap(byte[] outgoing, int offset, int len)
abstract byte[]
evaluateChallenge(byte[] challenge)
Evaluates the challenge data and generates a response.
String
getAuthorizationID()
String
getMechanismName()
Returns the IANA-registered mechanism name of this SASL client. (e.g.
protected String
getNegotiatedMaxBuffer()
protected String
getNegotiatedPolicyForwardSecrecy()
protected String
getNegotiatedPolicyNoActive()
protected String
getNegotiatedPolicyNoAnonymous()
protected String
getNegotiatedPolicyNoDictionary()
protected String
getNegotiatedPolicyNoPlainText()
protected String
getNegotiatedPolicyPassCredentials()
Object
getNegotiatedProperty(String propName)
Retrieves the negotiated property.
protected String
getNegotiatedQOP()
protected String
getNegotiatedRawSendSize()
protected String
getNegotiatedServerAuth()
protected String
getNegotiatedStrength()
protected String
getReuse()
abstract boolean
hasInitialResponse()
Determines if this mechanism has an optional initial response.
void
init(Map<K,V> attributes)
Initialises the mechanism with designated attributes.
protected abstract void
initMechanism()
boolean
isComplete()
Determines if the authentication exchange has completed.
void
reset()
Resets the mechanism instance for re-initialisation and use with other characteristics.
protected abstract void
resetMechanism()
byte[]
unwrap(byte[] incoming, int offset, int len)
Unwraps a byte array received from the server.
byte[]
wrap(byte[] outgoing, int offset, int len)
Wraps a byte array to be sent to the server.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

authorizationID

protected String authorizationID
The authorisation identity.

channelBinding

protected byte[] channelBinding
Channel binding data to use with this mechanism instance.

complete

protected boolean complete
Whether authentication phase is completed (true) or not (false).

handler

protected CallbackHandler handler
Callback handler to use with this mechanism instance.

mechanism

protected String mechanism
Name of this mechanism.

properties

protected Map<K,V> properties
Properties of qualities desired for this mechanism.

protocol

protected String protocol
Name of protocol using this mechanism.

serverName

protected String serverName
Name of server to authenticate to.

state

protected int state
The state of the authentication automaton.

Constructor Details

ClientMechanism

protected ClientMechanism(String mechanism)

Method Details

dispose

public void dispose()
            throws SaslException
Disposes of any system resources or security-sensitive information the SaslClient might be using. Invoking this method invalidates the SaslClient instance. This method is idempotent.
Specified by:
dispose in interface SaslClient
Throws:
SaslException - if a problem was encountered while disposing of the resources.

engineUnwrap

protected byte[] engineUnwrap(byte[] incoming,
                              int offset,
                              int len)
            throws SaslException

engineWrap

protected byte[] engineWrap(byte[] outgoing,
                            int offset,
                            int len)
            throws SaslException

evaluateChallenge

public abstract byte[] evaluateChallenge(byte[] challenge)
            throws SaslException
Evaluates the challenge data and generates a response. If a challenge is received from the server during the authentication process, this method is called to prepare an appropriate next response to submit to the server.
Specified by:
evaluateChallenge in interface SaslClient
Parameters:
challenge - the non-null challenge sent from the server. The challenge array may have zero length.
Returns:
the possibly null reponse to send to the server. It is null if the challenge accompanied a "SUCCESS" status and the challenge only contains data for the client to update its state and no response needs to be sent to the server. The response is a zero-length byte array if the client is to send a response with no data.
Throws:
SaslException - if an error occurred while processing the challenge or generating a response.

getAuthorizationID

public String getAuthorizationID()

getMechanismName

public String getMechanismName()
Returns the IANA-registered mechanism name of this SASL client. (e.g. "CRAM-MD5", "GSSAPI").
Specified by:
getMechanismName in interface SaslClient
Returns:
a non-null string representing the IANA-registered mechanism name.

getNegotiatedMaxBuffer

protected String getNegotiatedMaxBuffer()

getNegotiatedPolicyForwardSecrecy

protected String getNegotiatedPolicyForwardSecrecy()

getNegotiatedPolicyNoActive

protected String getNegotiatedPolicyNoActive()

getNegotiatedPolicyNoAnonymous

protected String getNegotiatedPolicyNoAnonymous()

getNegotiatedPolicyNoDictionary

protected String getNegotiatedPolicyNoDictionary()

getNegotiatedPolicyNoPlainText

protected String getNegotiatedPolicyNoPlainText()

getNegotiatedPolicyPassCredentials

protected String getNegotiatedPolicyPassCredentials()

getNegotiatedProperty

public Object getNegotiatedProperty(String propName)
Retrieves the negotiated property. This method can be called only after the authentication exchange has completed (i.e., when SaslClient.isComplete() returns true); otherwise, an IllegalStateException is thrown.
Specified by:
getNegotiatedProperty in interface SaslClient
Parameters:
propName - the non-null property name.
Returns:
the value of the negotiated property. If null, the property was not negotiated or is not applicable to this mechanism.
Throws:
IllegalStateException - if this authentication exchange has not completed.

getNegotiatedQOP

protected String getNegotiatedQOP()

getNegotiatedRawSendSize

protected String getNegotiatedRawSendSize()

getNegotiatedServerAuth

protected String getNegotiatedServerAuth()

getNegotiatedStrength

protected String getNegotiatedStrength()

getReuse

protected String getReuse()

hasInitialResponse

public abstract boolean hasInitialResponse()
Determines if this mechanism has an optional initial response. If true, caller should call SaslClient.evaluateChallenge(byte[]) with an empty array to get the initial response.
Specified by:
hasInitialResponse in interface SaslClient
Returns:
true if this mechanism has an initial response.

init

public void init(Map<K,V> attributes)
            throws SaslException
Initialises the mechanism with designated attributes. Permissible names and values are mechanism specific.
Parameters:
attributes - a set of name-value pairs that describes the desired future behaviour of this instance.
Throws:
SaslException - if an exception occurs during the process.

initMechanism

protected abstract void initMechanism()
            throws SaslException

isComplete

public boolean isComplete()
Determines if the authentication exchange has completed. This method may be called at any time, but typically, it will not be called until the caller has received indication from the server (in a protocol-specific manner) that the exchange has completed.
Specified by:
isComplete in interface SaslClient
Returns:
true if the authentication exchange has completed; false otherwise.

reset

public void reset()
            throws SaslException
Resets the mechanism instance for re-initialisation and use with other characteristics.
Throws:
SaslException - if an exception occurs during the process.

resetMechanism

protected abstract void resetMechanism()
            throws SaslException

unwrap

public byte[] unwrap(byte[] incoming,
                     int offset,
                     int len)
            throws SaslException
Unwraps a byte array received from the server. This method can be called only after the authentication exchange has completed (i.e., when SaslClient.isComplete() returns true) and only if the authentication exchange has negotiated integrity and/or privacy as the quality of protection; otherwise, an IllegalStateException is thrown.

incoming is the contents of the SASL buffer as defined in RFC 2222 without the leading four octet field that represents the length. offset and len specify the portion of incoming to use.

Specified by:
unwrap in interface SaslClient
Parameters:
incoming - a non-null byte array containing the encoded bytes from the server.
offset - the starting position at incoming of the bytes to use.
len - the number of bytes from incoming to use.
Returns:
a non-null byte array containing the decoded bytes.
Throws:
SaslException - if incoming cannot be successfully unwrapped.
IllegalStateException - if the authentication exchange has not completed, or if the negotiated quality of protection has neither integrity nor privacy.

wrap

public byte[] wrap(byte[] outgoing,
                   int offset,
                   int len)
            throws SaslException
Wraps a byte array to be sent to the server. This method can be called only after the authentication exchange has completed (i.e., when SaslClient.isComplete() returns true) and only if the authentication exchange has negotiated integrity and/or privacy as the quality of protection; otherwise, an IllegalStateException is thrown.

The result of this method will make up the contents of the SASL buffer as defined in RFC 2222 without the leading four octet field that represents the length. offset and len specify the portion of outgoing to use.

Specified by:
wrap in interface SaslClient
Parameters:
outgoing - a non-null byte array containing the bytes to encode.
offset - the starting position at outgoing of the bytes to use.
len - the number of bytes from outgoing to use.
Returns:
a non-null byte array containing the encoded bytes.
Throws:
SaslException - if outgoing cannot be successfully wrapped.
IllegalStateException - if the authentication exchange has not completed, or if the negotiated quality of protection has neither integrity nor privacy.

ClientMechanism.java -- Copyright (C) 2003, 2005, 2006 Free Software Foundation, Inc. This file is a part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.