org.forgerock.opendj.ldap.messages

Interface BindRequest

All Superinterfaces:

ProtocolOp, Request

public interface BindRequest
extends Request

The Bind operation allows authentication information to be exchanged between the client and server. The Bind operation should be thought of as the "authenticate" operation.

Nested Class Summary

Nested classes/interfaces inherited from interface org.forgerock.opendj.ldap.messages.Request

Request.RequestType

Field Summary

Fields

Modifier and Type	Field and Description
static byte	AUTHENTICATION_TYPE_SASL The authentication type value (0xA3) reserved for SASL authentication.
static byte	AUTHENTICATION_TYPE_SIMPLE The authentication type value (0x80) reserved for simple authentication.
static String	SASL_MECHANISM_NAME_ANONYMOUS The name of the SASL mechanism that uses anonymous access and having the name "ANONYMOUS".
static String	SASL_MECHANISM_NAME_CRAM_MD5 The name of the SASL mechanism that uses CRAM-MD5 authentication and having the name "CRAM-MD5".
static String	SASL_MECHANISM_NAME_DIGEST_MD5 The name of the SASL mechanism that uses DIGEST-MD5 authentication and having the name "DIGEST-MD5".
static String	SASL_MECHANISM_NAME_EXTERNAL The name of the SASL mechanism that uses external authentication and having the name "EXTERNAL".
static String	SASL_MECHANISM_NAME_GSSAPI The name of the SASL mechanism that uses GSS-API authentication and having the name "GSSAPI".
static String	SASL_MECHANISM_NAME_PLAIN The name of the SASL mechanism that uses PLAIN authentication and having the name "PLAIN".

Method Summary

Modifier and Type	Method and Description
BindRequest	addControl(Control control) Adds the provided control to this protocol-op.
BindRequest	addControls(Iterable<? extends Control> controls) Adds the provided controls to this protocol-op.
void	destroy() Destroys the credentials contained within this bind request.
BindRequest	evaluateSaslChallenge(byte[] serverSaslCredentials) Evaluates the provided SASL credentials (challenge) returned by the server and creates the next SASL bind request that should be sent to the server in order to continue or complete the SASL authentication sequence.
byte	getAuthenticationType() Returns the authentication mechanism identifier for this bind request as defined by the LDAP protocol.
byte[]	getAuthenticationValue() Returns a defensive copy of the encoded authentication value for this bind request as defined by the LDAP protocol.
<C extends Control> C	getControl(ControlDecoder<C> decoder, DecodeOptions options) Decodes and returns the first control in this protocol-op having an OID corresponding to the provided control decoder.
List<Control>	getControls() Returns a List containing the controls included with this protocol-op.
Dn	getName() Returns the name of the Directory object that the client wishes to bind as.
SaslClient	getSaslClient() Returns the SaslClient that will be responsible for continuing the SASL challenge-response sequence as well as potentially installing a SASL security layer once the bind sequence completes, or null if a no SaslClient has been provided.
byte[]	getSaslCredentials() Returns a defensive copy of the optional SASL credentials, or null if the authentication type is not AUTHENTICATION_TYPE_SASL or if the SASL credentials are not present.
String	getSaslMechanism() Returns the name of the SASL mechanism, e.g.
byte[]	getSimplePassword() Returns a defensive copy of the simple bind password, or null if the authentication type is not AUTHENTICATION_TYPE_SIMPLE.
int	getVersion() Returns the version of the protocol to be used at the LDAP message layer.
boolean	hasNegotiatedSaslQop() Returns true if the SASL bind sequence has negotiated a SASL security layer using Quality of Protection (QOP).
boolean	isSaslBindRequest() Return true if this bind request's authentication type is AUTHENTICATION_TYPE_SASL.
boolean	isSimpleBindRequest() Return true if this bind request's authentication type is AUTHENTICATION_TYPE_SIMPLE.
BindRequest	setAuthenticationTypeAndValue(byte type, byte[] value) Sets the authentication type and value.
BindRequest	setName(Dn name) Sets the name of the Directory object that the client wishes to bind as.
BindRequest	setSaslMechanismAndCredentials(SaslClient saslClient) Configures this bind request for SASL authentication using the provided SaslClient.
BindRequest	setSaslMechanismAndCredentials(String mechanism, byte[] credentials) Sets the authentication type to AUTHENTICATION_TYPE_SASL, the SASL mechanism name, and the optional SASL credentials.
BindRequest	setSimplePassword(byte[] password) Sets the authentication type to AUTHENTICATION_TYPE_SIMPLE and the authentication value to a copy of the provided password.
BindRequest	setVersion(int version) Sets the version of the protocol to be used at the LDAP message layer.

Methods inherited from interface org.forgerock.opendj.ldap.messages.Request

accept, getType

Methods inherited from interface org.forgerock.opendj.ldap.messages.ProtocolOp

containsControl, getControl

Field Detail

AUTHENTICATION_TYPE_SIMPLE

static final byte AUTHENTICATION_TYPE_SIMPLE

The authentication type value (0x80) reserved for simple authentication.

See Also:

Constant Field Values

AUTHENTICATION_TYPE_SASL

static final byte AUTHENTICATION_TYPE_SASL

The authentication type value (0xA3) reserved for SASL authentication.

See Also:

Constant Field Values

SASL_MECHANISM_NAME_ANONYMOUS

static final String SASL_MECHANISM_NAME_ANONYMOUS

The name of the SASL mechanism that uses anonymous access and having the name "ANONYMOUS".

See Also:

Constant Field Values

SASL_MECHANISM_NAME_CRAM_MD5

static final String SASL_MECHANISM_NAME_CRAM_MD5

The name of the SASL mechanism that uses CRAM-MD5 authentication and having the name "CRAM-MD5".

See Also:

Constant Field Values

SASL_MECHANISM_NAME_DIGEST_MD5

static final String SASL_MECHANISM_NAME_DIGEST_MD5

The name of the SASL mechanism that uses DIGEST-MD5 authentication and having the name "DIGEST-MD5".

See Also:

Constant Field Values

SASL_MECHANISM_NAME_PLAIN

static final String SASL_MECHANISM_NAME_PLAIN

The name of the SASL mechanism that uses PLAIN authentication and having the name "PLAIN".

See Also:

Constant Field Values

SASL_MECHANISM_NAME_EXTERNAL

static final String SASL_MECHANISM_NAME_EXTERNAL

The name of the SASL mechanism that uses external authentication and having the name "EXTERNAL".

See Also:

Constant Field Values

SASL_MECHANISM_NAME_GSSAPI

static final String SASL_MECHANISM_NAME_GSSAPI

The name of the SASL mechanism that uses GSS-API authentication and having the name "GSSAPI".

See Also:

Constant Field Values

Method Detail

getVersion

int getVersion()

Returns the version of the protocol to be used at the LDAP message layer. There is no version negotiation. The client sets this field to the version it desires. If the server does not support the specified version then it will respond with a result whose error code is ResultCode.PROTOCOL_ERROR.

By default LDAP version 3 will be used which is the most recent LDAP version and the one recommended for all client applications. Furthermore, OpenDJ only has partial support for LDAPv2.

Returns:

The version of the protocol to be used at the LDAP message layer.

setVersion

BindRequest setVersion(int version)

Sets the version of the protocol to be used at the LDAP message layer. There is no version negotiation. The client sets this field to the version it desires. If the server does not support the specified version then it will respond with a result whose error code is ResultCode.PROTOCOL_ERROR.

By default LDAP version 3 will be used which is the most recent LDAP version and the one recommended for all client applications. Furthermore, OpenDJ only has partial support for LDAPv2.

Parameters:

version - The version of the protocol to be used at the LDAP message layer.

Returns:

This bind request.

Throws:

IllegalArgumentException - If version is less than 1 or greater than 127.

UnsupportedOperationException - If this bind request does not permit the version to be set.

getName

Dn getName()

Returns the name of the Directory object that the client wishes to bind as. The name may be empty (but never null) when used for anonymous binds, or when using SASL authentication. The server shall not dereference any aliases in locating the named object.

The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

Returns:

The name of the Directory object that the client wishes to bind as. May be empty, but cannot be null.

setName

BindRequest setName(Dn name)

Sets the name of the Directory object that the client wishes to bind as. The name may be empty (but never null when used for of anonymous binds, or when using SASL authentication. The server shall not dereference any aliases in locating the named object.

The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

Parameters:

name - The name of the Directory object that the client wishes to bind as. May be empty, but cannot be null.

Returns:

This bind request.

Throws:

UnsupportedOperationException - If this bind request does not permit the distinguished name to be set.

NullPointerException - If name was null.

getAuthenticationType

byte getAuthenticationType()

Returns the authentication mechanism identifier for this bind request as defined by the LDAP protocol. Note that the value AUTHENTICATION_TYPE_SIMPLE (0x80) is reserved for simple authentication and the value AUTHENTICATION_TYPE_SASL ( 0xA3) is reserved for SASL authentication.

Returns:

The authentication mechanism identifier.

isSimpleBindRequest

boolean isSimpleBindRequest()

Return true if this bind request's authentication type is AUTHENTICATION_TYPE_SIMPLE.

Returns:

true if this bind request's authentication type is AUTHENTICATION_TYPE_SIMPLE.

isSaslBindRequest

boolean isSaslBindRequest()

Return true if this bind request's authentication type is AUTHENTICATION_TYPE_SASL.

Returns:

true if this bind request's authentication type is AUTHENTICATION_TYPE_SASL.

getAuthenticationValue

byte[] getAuthenticationValue()

Returns a defensive copy of the encoded authentication value for this bind request as defined by the LDAP protocol. For simple authentication the authentication value is the byte representation of the password. For SASL authentication the authentication value is an ASN.1 encoded sequence comprising of the SASL mechanism name and the optional SASL mechanism specific credentials.

Returns:

A defensive copy of the encoded authentication value for this bind request as defined by the LDAP protocol.

setAuthenticationTypeAndValue

BindRequest setAuthenticationTypeAndValue(byte type,
                                          byte[] value)
                                   throws IOException

Sets the authentication type and value. If type is equal to AUTHENTICATION_TYPE_SIMPLE then the value will be interpreted as the password. If type is equal to AUTHENTICATION_TYPE_SASL then the value will be interpreted as the encoded SASL mechanism and credentials. Otherwise, the value will be interpreted as an unrecognized extended authentication value.

Parameters:

type - The authentication mechanism identifier.

value - The encoded authentication value for this bind request as defined by the LDAP protocol, which may be an empty array but must not be null. The value will be defensively copied.

Returns:

This bind request.

Throws:

IOException - If the authentication type is AUTHENTICATION_TYPE_SASL and the value could not be decoded as an encoded SASL mechanism and credentials.

UnsupportedOperationException - If this bind request does not permit the authentication type or value to be set.

NullPointerException - If value was null.

getSimplePassword

byte[] getSimplePassword()

Returns a defensive copy of the simple bind password, or null if the authentication type is not AUTHENTICATION_TYPE_SIMPLE.

Returns:

A defensive copy of the simple bind password, or null if the authentication type is not AUTHENTICATION_TYPE_SIMPLE.

setSimplePassword

BindRequest setSimplePassword(byte[] password)

Sets the authentication type to AUTHENTICATION_TYPE_SIMPLE and the authentication value to a copy of the provided password.

Parameters:

password - The non-null simple bind password, which will be defensively copied.

Returns:

This bind request.

Throws:

UnsupportedOperationException - If this bind request does not permit the authentication type or value to be set.

NullPointerException - If password was null.

getSaslMechanism

String getSaslMechanism()

Returns the name of the SASL mechanism, e.g. SASL_MECHANISM_NAME_PLAIN, or null if the authentication type is not AUTHENTICATION_TYPE_SASL.

Returns:

The name of the SASL mechanism, e.g. SASL_MECHANISM_NAME_PLAIN, or null if the authentication type is not AUTHENTICATION_TYPE_SASL.

getSaslCredentials

byte[] getSaslCredentials()

Returns a defensive copy of the optional SASL credentials, or null if the authentication type is not AUTHENTICATION_TYPE_SASL or if the SASL credentials are not present.

Returns:

A defensive copy of the optional SASL credentials, or null if the authentication type is not AUTHENTICATION_TYPE_SASL or if the SASL credentials are not present.

getSaslClient

SaslClient getSaslClient()

Returns the SaslClient that will be responsible for continuing the SASL challenge-response sequence as well as potentially installing a SASL security layer once the bind sequence completes, or null if a no SaslClient has been provided.

A SaslClient is only required if the application is performing SASL authentication and wishes the network layer (e.g. Grizzly) to drive the complete challenge-response sequence. An application may choose to drive the SASL bind sequence itself, but the application:

1. will not be able to control where bind requests are sent if load-balancing is active,
2. nor will it be able to install a security layer upon completion of the bind sequence.

Returns:

The SaslClient that will be responsible for continuing the SASL challenge-response sequence, as well as potentially installing a SASL security layer once the bind sequence completes, or null if none has been provided.

See Also:

setSaslMechanismAndCredentials(SaslClient)

setSaslMechanismAndCredentials

BindRequest setSaslMechanismAndCredentials(String mechanism,
                                           byte[] credentials)

Sets the authentication type to AUTHENTICATION_TYPE_SASL, the SASL mechanism name, and the optional SASL credentials.

Parameters:

mechanism - The SASL mechanism name, such as SASL_MECHANISM_NAME_PLAIN.

credentials - The optional SASL credentials which will be defensively copied if provided.

Returns:

This bind request.

Throws:

UnsupportedOperationException - If this bind request does not permit the authentication type or value to be set.

NullPointerException - If mechanism was null.

setSaslMechanismAndCredentials

BindRequest setSaslMechanismAndCredentials(SaslClient saslClient)

Configures this bind request for SASL authentication using the provided SaslClient. The authentication type will be set to AUTHENTICATION_TYPE_SASL, the SASL mechanism name will be obtained from the SaslClient, and the SASL credentials will be derived from the SaslClient if it has an initial response, otherwise they will be left undefined.

This method should be used if the application is performing SASL authentication and wishes the network layer (e.g. Grizzly) to drive the complete challenge-response sequence. An application may choose to drive the SASL bind sequence itself, but the application a) will not be able to control where bind requests are sent if load-balancing is active, b) nor will it be able to install a security layer upon completion of the bind sequence if one is negotiated.

Parameters:

saslClient - The SaslClient that will be responsible for continuing the SASL challenge-response sequence, as well as potentially installing a SASL security layer once the bind sequence completes.

Returns:

This bind request.

Throws:

IllegalArgumentException - If the provided SASL client has not been configured correctly.

UnsupportedOperationException - If this bind request does not permit the SaslClient to be set.

NullPointerException - If saslClient was null.

evaluateSaslChallenge

BindRequest evaluateSaslChallenge(byte[] serverSaslCredentials)
                           throws SaslException

Evaluates the provided SASL credentials (challenge) returned by the server and creates the next SASL bind request that should be sent to the server in order to continue or complete the SASL authentication sequence. This method may only be called if this request has been configured to use a SaslClient.

Parameters:

serverSaslCredentials - The non-null SASL challenge sent from the server, which may be empty.

Returns:

The next SASL bind request to be sent to the server, or null if the SASL bind sequence has completed.

Throws:

SaslException - If an error occurred while evaluating the challenge or generating a response.

IllegalStateException - If this bind request has not been configured to use a SaslClient.

NullPointerException - If serverSaslCredentials was null.

See Also:

setSaslMechanismAndCredentials(SaslClient)

hasNegotiatedSaslQop

boolean hasNegotiatedSaslQop()

Returns true if the SASL bind sequence has negotiated a SASL security layer using Quality of Protection (QOP). This method may only be called if this request has been configured to use a SaslClient and the SASL bind sequence has completed (the previous call to evaluateSaslChallenge(byte[]) returned null).

Returns:

true if the SASL bind sequence has negotiated a SASL security layer (QOP).

Throws:

IllegalStateException - If this bind request has not been configured to use a SaslClient or the SASL bind sequence has not completed.

See Also:

setSaslMechanismAndCredentials(SaslClient)

addControl

BindRequest addControl(Control control)

Description copied from interface: ProtocolOp

Adds the provided control to this protocol-op.

Specified by:

addControl in interface ProtocolOp

Specified by:

addControl in interface Request

Parameters:

control - The control to be added to this protocol-op.

Returns:

This protocol-op.

addControls

BindRequest addControls(Iterable<? extends Control> controls)

Description copied from interface: ProtocolOp

Adds the provided controls to this protocol-op.

Specified by:

addControls in interface ProtocolOp

Specified by:

addControls in interface Request

Parameters:

controls - The controls to be added to this protocol-op.

Returns:

This protocol-op.

getControl

<C extends Control> C getControl(ControlDecoder<C> decoder,
                                 DecodeOptions options)
                          throws DecodeException

Description copied from interface: ProtocolOp

Decodes and returns the first control in this protocol-op having an OID corresponding to the provided control decoder.

Specified by:

getControl in interface ProtocolOp

Type Parameters:

C - The type of control to be decoded and returned.

Parameters:

decoder - The control decoder.

options - The set of decode options which should be used when decoding the control.

Returns:

The decoded control, or null if the control is not included with this protocol-op.

Throws:

DecodeException - If the control could not be decoded because it was malformed in some way (e.g. the control value was missing, or its content could not be decoded).

getControls

List<Control> getControls()

Description copied from interface: ProtocolOp

Returns a List containing the controls included with this protocol-op. The returned List may be modified if permitted by this protocol-op.

Specified by:

getControls in interface ProtocolOp

Returns:

A List containing the controls.

destroy

void destroy()

Destroys the credentials contained within this bind request. This method does not dispose the SaslClient. Instead the underlying network layer will dispose of the SaslClient when it is no longer in use. This bind request can no longer be used once this method returns.