001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *  
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *  
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License. 
018 *  
019 */
020package org.apache.directory.shared.ldap.model.message;
021
022
023import org.apache.directory.shared.ldap.model.exception.MessageException;
024import org.apache.directory.shared.ldap.model.name.Dn;
025
026
027/**
028 * Bind protocol operation request which authenticates and begins a client
029 * session. Does not yet contain interfaces for SASL authentication mechanisms.
030 * 
031 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
032 */
033public interface BindRequest extends SingleReplyRequest<BindResponse>, AbandonableRequest
034{
035    /** Bind request message type enumeration value */
036    MessageTypeEnum TYPE = MessageTypeEnum.BIND_REQUEST;
037
038    /** Bind response message type enumeration value */
039    MessageTypeEnum RESP_TYPE = BindResponse.TYPE;
040
041
042    /**
043     * Checks to see if the authentication mechanism is simple and not SASL
044     * based.
045     * 
046     * @return true if the mechanism is simple false if it is SASL based.
047     */
048    boolean isSimple();
049
050
051    /**
052     * Checks to see if the authentication mechanism is simple and not SASL
053     * based.
054     * 
055     * @return true if the mechanism is simple false if it is SASL based.
056     */
057    boolean getSimple();
058
059
060    /**
061     * Sets the authentication mechanism to simple or to SASL based
062     * authentication.
063     * 
064     * @param isSimple true if authentication is simple, false otherwise.
065     * @return The BindRequest instance
066     */
067    BindRequest setSimple( boolean isSimple );
068
069
070    /**
071     * Gets the simple credentials associated with a simple authentication
072     * attempt or null if this request uses SASL authentication mechanisms.
073     * 
074     * @return null if the mechanism is SASL, or the credentials if it is simple.
075     */
076    byte[] getCredentials();
077
078
079    /**
080     * Sets the simple credentials associated with a simple authentication
081     * attempt. Ignored if this request uses SASL authentication mechanisms.
082     * 
083     * @param credentials the credentials if authentication is simple
084     * @return The BindRequest instance
085     */
086    BindRequest setCredentials( String credentials );
087
088
089    /**
090     * Sets the simple credentials associated with a simple authentication
091     * attempt. Ignored if this request uses SASL authentication mechanisms.
092     * 
093     * @param credentials the credentials if authentication is simple
094     * @return The BindRequest instance
095     */
096    BindRequest setCredentials( byte[] credentials );
097
098
099    /**
100     * Gets the distinguished name of the subject in this authentication
101     * request. This field may take on a null value (a zero length string) for
102     * the purposes of anonymous binds, when authentication has been performed
103     * at a lower layer, or when using SASL credentials with a mechanism that
104     * includes the Dn in the credentials.
105     * 
106     * @return the Dn of the authenticating user.
107     */
108    Dn getName();
109
110
111    /**
112     * Sets the distinguished name of the subject in this authentication
113     * request. This field may take on a null value (or a zero length string)
114     * for the purposes of anonymous binds, when authentication has been
115     * performed at a lower layer, or when using SASL credentials with a
116     * mechanism that includes the Dn in the credentials.
117     * 
118     * @param name the Dn of the authenticating user - leave null for annonymous user.
119     * @return The BindRequest instance
120     */
121    BindRequest setName( Dn name );
122
123
124    /**
125     * Checks to see if the Ldap v3 protocol is used. Normally this would
126     * extract a version number from the bind request sent by the client
127     * indicating the version of the protocol to be used in this protocol
128     * session. The integer is either a 2 or a 3 at the moment. We thought it
129     * was better to just check if the protocol used is 3 or not rather than use
130     * an type-safe enumeration type for a binary value. If an LDAPv4 comes out
131     * then we shall convert the return type to a type safe enumeration.
132     * 
133     * @return true if client using version 3 false if it is version 2.
134     */
135    boolean isVersion3();
136
137
138    /**
139     * Gets whether or not the Ldap v3 protocol is used. Normally this would
140     * extract a version number from the bind request sent by the client
141     * indicating the version of the protocol to be used in this protocol
142     * session. The integer is either a 2 or a 3 at the moment. We thought it
143     * was better to just check if the protocol used is 3 or not rather than use
144     * an type-safe enumeration type for a binary value. If an LDAPv4 comes out
145     * then we shall convert the return type to a type safe enumeration.
146     * 
147     * @return true if client using version 3 false if it is version 2.
148     */
149    boolean getVersion3();
150
151
152    /**
153     * Sets whether or not the LDAP v3 or v2 protocol is used. Normally this
154     * would extract a version number from the bind request sent by the client
155     * indicating the version of the protocol to be used in this protocol
156     * session. The integer is either a 2 or a 3 at the moment. We thought it
157     * was better to just check if the protocol used is 3 or not rather than use
158     * an type-safe enumeration type for a binary value. If an LDAPv4 comes out
159     * then we shall convert the return type to a type safe enumeration.
160     * 
161     * @param isVersion3 if true the client will be exhibiting version 3 bind behavior,
162     *  If false is used version 2 behavior will be exhibited.
163     * @return The BindRequest instance
164     */
165    BindRequest setVersion3( boolean isVersion3 );
166
167
168    /**
169     * Gets the SASL mechanism String associated with this BindRequest if the
170     * bind operation is using SASL.
171     * 
172     * @return the SASL mechanism or null if the bind operation is simple
173     */
174    String getSaslMechanism();
175
176
177    /**
178     * Sets the SASL mechanism String associated with this BindRequest if the
179     * bind operation is using SASL.
180     * 
181     * @param saslMechanism the SASL mechanism
182     * @return The BindRequest instance
183     */
184    BindRequest setSaslMechanism( String saslMechanism );
185
186
187    /**
188     * {@inheritDoc}
189     */
190    BindRequest setMessageId( int messageId );
191    
192    
193    /**
194     * {@inheritDoc}
195     */
196    BindRequest addControl( Control control ) throws MessageException;
197    
198    
199    /**
200     * {@inheritDoc}
201     */
202    BindRequest addAllControls( Control[] controls ) throws MessageException;
203    
204    
205    /**
206     * {@inheritDoc}
207     */
208    BindRequest removeControl( Control control ) throws MessageException;
209}