View Javadoc
1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  You may obtain a copy of the License at
9    *  
10   *    http://www.apache.org/licenses/LICENSE-2.0
11   *  
12   *  Unless required by applicable law or agreed to in writing,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License. 
18   *  
19   */
20  package org.apache.directory.api.ldap.model.message;
21  
22  
23  import org.apache.directory.api.ldap.model.name.Dn;
24  
25  
26  /**
27   * Bind protocol operation request which authenticates and begins a client
28   * session. Does not yet contain interfaces for SASL authentication mechanisms.
29   * 
30   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
31   */
32  public interface BindRequest extends SingleReplyRequest, AbandonableRequest
33  {
34      /**
35       * Checks to see if the authentication mechanism is simple and not SASL
36       * based.
37       * 
38       * @return true if the mechanism is simple false if it is SASL based.
39       */
40      boolean isSimple();
41  
42  
43      /**
44       * Checks to see if the authentication mechanism is simple and not SASL
45       * based.
46       * 
47       * @return true if the mechanism is simple false if it is SASL based.
48       */
49      boolean getSimple();
50  
51  
52      /**
53       * Sets the authentication mechanism to simple or to SASL based
54       * authentication.
55       * 
56       * @param isSimple true if authentication is simple, false otherwise.
57       * @return The BindRequest instance
58       */
59      BindRequest setSimple( boolean isSimple );
60  
61  
62      /**
63       * Gets the simple credentials associated with a simple authentication
64       * attempt or null if this request uses SASL authentication mechanisms.
65       * 
66       * @return null if the mechanism is SASL, or the credentials if it is simple.
67       */
68      byte[] getCredentials();
69  
70  
71      /**
72       * Sets the simple credentials associated with a simple authentication
73       * attempt. Ignored if this request uses SASL authentication mechanisms.
74       * 
75       * @param credentials the credentials if authentication is simple
76       * @return The BindRequest instance
77       */
78      BindRequest setCredentials( String credentials );
79  
80  
81      /**
82       * Sets the simple credentials associated with a simple authentication
83       * attempt. Ignored if this request uses SASL authentication mechanisms.
84       * 
85       * @param credentials the credentials if authentication is simple
86       * @return The BindRequest instance
87       */
88      BindRequest setCredentials( byte[] credentials );
89  
90  
91      /**
92       * Gets the name of the subject in this authentication
93       * request. This field may take on a null value (a zero length string) for
94       * the purposes of anonymous binds, when authentication has been performed
95       * at a lower layer, or when using SASL credentials with a mechanism that
96       * includes the name in the credentials.
97       * 
98       * @return the name of the authenticating user.
99       */
100     String getName();
101 
102 
103     /**
104      * Sets the  name of the subject in this authentication
105      * request. This field may take on a null value (or a zero length string)
106      * for the purposes of anonymous binds, when authentication has been
107      * performed at a lower layer, or when using SASL credentials with a
108      * mechanism that includes the name in the credentials.
109      * 
110      * @param name the name of the authenticating user - leave null for anonymous user.
111      * @return The BindRequest instance
112      */
113     BindRequest setName( String name );
114 
115 
116     /**
117      * Gets the DN of the subject in this authentication
118      * request. This field may take on a null value (a zero length string) for
119      * the purposes of anonymous binds, when authentication has been performed
120      * at a lower layer, or when using SASL credentials with a mechanism that
121      * includes the DN in the credentials.
122      * 
123      * @return the DN of the authenticating user.
124      */
125     Dn getDn();
126 
127 
128     /**
129      * Sets the DN of the subject in this authentication
130      * request. This field may take on a null value (or a zero length string)
131      * for the purposes of anonymous binds, when authentication has been
132      * performed at a lower layer, or when using SASL credentials with a
133      * mechanism that includes the DN in the credentials.
134      * 
135      * @param name the DN of the authenticating user - leave null for anonymous user.
136      * @return The BindRequest instance
137      */
138     BindRequest setDn( Dn name );
139 
140 
141     /**
142      * Checks to see if the Ldap v3 protocol is used. Normally this would
143      * extract a version number from the bind request sent by the client
144      * indicating the version of the protocol to be used in this protocol
145      * session. The integer is either a 2 or a 3 at the moment. We thought it
146      * was better to just check if the protocol used is 3 or not rather than use
147      * an type-safe enumeration type for a binary value. If an LDAPv4 comes out
148      * then we shall convert the return type to a type safe enumeration.
149      * 
150      * @return true if client using version 3 false if it is version 2.
151      */
152     boolean isVersion3();
153 
154 
155     /**
156      * Gets whether or not the Ldap v3 protocol is used. Normally this would
157      * extract a version number from the bind request sent by the client
158      * indicating the version of the protocol to be used in this protocol
159      * session. The integer is either a 2 or a 3 at the moment. We thought it
160      * was better to just check if the protocol used is 3 or not rather than use
161      * an type-safe enumeration type for a binary value. If an LDAPv4 comes out
162      * then we shall convert the return type to a type safe enumeration.
163      * 
164      * @return true if client using version 3 false if it is version 2.
165      */
166     boolean getVersion3();
167 
168 
169     /**
170      * Sets whether or not the LDAP v3 or v2 protocol is used. Normally this
171      * would extract a version number from the bind request sent by the client
172      * indicating the version of the protocol to be used in this protocol
173      * session. The integer is either a 2 or a 3 at the moment. We thought it
174      * was better to just check if the protocol used is 3 or not rather than use
175      * an type-safe enumeration type for a binary value. If an LDAPv4 comes out
176      * then we shall convert the return type to a type safe enumeration.
177      * 
178      * @param isVersion3 if true the client will be exhibiting version 3 bind behavior,
179      *  If false is used version 2 behavior will be exhibited.
180      * @return The BindRequest instance
181      */
182     BindRequest setVersion3( boolean isVersion3 );
183 
184 
185     /**
186      * Gets the SASL mechanism String associated with this BindRequest if the
187      * bind operation is using SASL.
188      * 
189      * @return the SASL mechanism or null if the bind operation is simple
190      */
191     String getSaslMechanism();
192 
193 
194     /**
195      * Sets the SASL mechanism String associated with this BindRequest if the
196      * bind operation is using SASL.
197      * 
198      * @param saslMechanism the SASL mechanism
199      * @return The BindRequest instance
200      */
201     BindRequest setSaslMechanism( String saslMechanism );
202 
203 
204     /**
205      * {@inheritDoc}
206      */
207     BindRequest setMessageId( int messageId );
208 
209 
210     /**
211      * {@inheritDoc}
212      */
213     BindRequest addControl( Control control );
214 
215 
216     /**
217      * {@inheritDoc}
218      */
219     BindRequest addAllControls( Control[] controls );
220 
221 
222     /**
223      * {@inheritDoc}
224      */
225     BindRequest removeControl( Control control );
226 }