001    /*
002     * CDDL HEADER START
003     *
004     * The contents of this file are subject to the terms of the
005     * Common Development and Distribution License, Version 1.0 only
006     * (the "License").  You may not use this file except in compliance
007     * with the License.
008     *
009     * You can obtain a copy of the license at
010     * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011     * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
012     * See the License for the specific language governing permissions
013     * and limitations under the License.
014     *
015     * When distributing Covered Code, include this CDDL HEADER in each
016     * file and include the License file at
017     * trunk/opends/resource/legal-notices/OpenDS.LICENSE.  If applicable,
018     * add the following below this CDDL HEADER, with the fields enclosed
019     * by brackets "[]" replaced with your own identifying information:
020     *      Portions Copyright [yyyy] [name of copyright owner]
021     *
022     * CDDL HEADER END
023     *
024     *
025     *      Copyright 2006-2008 Sun Microsystems, Inc.
026     */
027    package org.opends.server.core;
028    import org.opends.messages.Message;
029    
030    import org.opends.server.protocols.asn1.ASN1OctetString;
031    import org.opends.server.types.AuthenticationInfo;
032    import org.opends.server.types.AuthenticationType;
033    import org.opends.server.types.ByteString;
034    import org.opends.server.types.DN;
035    import org.opends.server.types.Entry;
036    import org.opends.server.types.Operation;
037    
038    
039    /**
040     * This interface defines an operation that may be used to authenticate a user
041     * to the Directory Server.  Note that for security restrictions, response
042     * messages that may be returned to the client must be carefully cleaned to
043     * ensure that they do not provide a malicious client with information that may
044     * be useful in an attack.  This does impact the debugability of the server,
045     * but that can be addressed by calling the <CODE>setAuthFailureReason</CODE>
046     * method, which can provide a reason for a failure in a form that will not be
047     * returned to the client but may be written to a log file.
048     */
049    public interface BindOperation extends Operation
050    {
051    
052      /**
053       * Retrieves the authentication type for this bind operation.
054       *
055       * @return  The authentication type for this bind operation.
056       */
057      public abstract AuthenticationType getAuthenticationType();
058    
059      /**
060       * Retrieves the raw, unprocessed bind DN for this bind operation as contained
061       * in the client request.  The value may not actually contain a valid DN, as
062       * no validation will have been performed.
063       *
064       * @return  The raw, unprocessed bind DN for this bind operation as contained
065       *          in the client request.
066       */
067      public abstract ByteString getRawBindDN();
068    
069      /**
070       * Specifies the raw, unprocessed bind DN for this bind operation.  This
071       * should only be called by pre-parse plugins.
072       *
073       * @param  rawBindDN  The raw, unprocessed bind DN for this bind operation.
074       */
075      public abstract void setRawBindDN(ByteString rawBindDN);
076    
077      /**
078       * Retrieves a string representation of the protocol version associated with
079       * this bind request.
080       *
081       * @return  A string representation of the protocol version associated with
082       *          this bind request.
083       */
084      public String getProtocolVersion();
085    
086      /**
087       * Specifies the string representation of the protocol version associated with
088       * this bind request.
089       *
090       * @param  protocolVersion  The string representation of the protocol version
091       *                          associated with this bind request.
092       */
093      public void setProtocolVersion(String protocolVersion);
094    
095      /**
096       * Retrieves the bind DN for this bind operation.  This method should not be
097       * called by pre-parse plugins, as the raw value will not have been processed
098       * by that time.  Instead, pre-parse plugins should call the
099       * <CODE>getRawBindDN</CODE> method.
100       *
101       * @return  The bind DN for this bind operation, or <CODE>null</CODE> if the
102       *          raw DN has not yet been processed.
103       */
104      public abstract DN getBindDN();
105    
106      /**
107       * Retrieves the simple authentication password for this bind operation.
108       *
109       * @return  The simple authentication password for this bind operation.
110       */
111      public abstract ByteString getSimplePassword();
112    
113      /**
114       * Specifies the simple authentication password for this bind operation.
115       *
116       * @param  simplePassword  The simple authentication password for this bind
117       *                         operation.
118       */
119      public abstract void setSimplePassword(ByteString simplePassword);
120    
121      /**
122       * Retrieves the SASL mechanism for this bind operation.
123       *
124       * @return  The SASL mechanism for this bind operation, or <CODE>null</CODE>
125       *          if the bind does not use SASL authentication.
126       */
127      public abstract String getSASLMechanism();
128    
129      /**
130       * Retrieves the SASL credentials for this bind operation.
131       *
132       * @return  The SASL credentials for this bind operation, or <CODE>null</CODE>
133       *          if there are none or if the bind does not use SASL authentication.
134       */
135      public abstract ASN1OctetString getSASLCredentials();
136    
137      /**
138       * Specifies the SASL credentials for this bind operation.
139       *
140       * @param  saslMechanism    The SASL mechanism for this bind operation.
141       * @param  saslCredentials  The SASL credentials for this bind operation, or
142       *                          <CODE>null</CODE> if there are none.
143       */
144      public abstract void setSASLCredentials(String saslMechanism,
145          ASN1OctetString saslCredentials);
146    
147      /**
148       * Retrieves the set of server SASL credentials to include in the bind
149       * response.
150       *
151       * @return  The set of server SASL credentials to include in the bind
152       *          response, or <CODE>null</CODE> if there are none.
153       */
154      public abstract ASN1OctetString getServerSASLCredentials();
155    
156      /**
157       * Specifies the set of server SASL credentials to include in the bind
158       * response.
159       *
160       * @param  serverSASLCredentials  The set of server SASL credentials to
161       *                                include in the bind response.
162       */
163      public abstract void setServerSASLCredentials(
164          ASN1OctetString serverSASLCredentials);
165    
166      /**
167       * Retrieves the user entry associated with the SASL authentication attempt.
168       * This should be set by any SASL mechanism in which the processing was able
169       * to get far enough to make this determination, regardless of whether the
170       * authentication was ultimately successful.
171       *
172       * @return  The user entry associated with the SASL authentication attempt, or
173       *          <CODE>null</CODE> if it was not a SASL authentication or the SASL
174       *          processing was not able to map the request to a user.
175       */
176      public abstract Entry getSASLAuthUserEntry();
177    
178      /**
179       * Specifies the user entry associated with the SASL authentication attempt.
180       * This should be set by any SASL mechanism in which the processing was able
181       * to get far enough to make this determination, regardless of whether the
182       * authentication was ultimately successful.
183       *
184       * @param  saslAuthUserEntry  The user entry associated with the SASL
185       *                            authentication attempt.
186       */
187      public abstract void setSASLAuthUserEntry(Entry saslAuthUserEntry);
188    
189      /**
190       * Retrieves a human-readable message providing the reason that the
191       * authentication failed, if available.
192       *
193       * @return  A human-readable message providing the reason that the
194       *          authentication failed, or <CODE>null</CODE> if none is available.
195       */
196      public abstract Message getAuthFailureReason();
197    
198      /**
199       * Specifies the reason that the authentication failed.
200       *
201       * @param  message providing the reason that the
202       *                 authentication failed.
203       */
204      public abstract void setAuthFailureReason(Message message);
205    
206      /**
207       * Retrieves the user entry DN for this bind operation.  It will only be
208       * available if the bind processing has proceeded far enough to identify the
209       * user attempting to authenticate.
210       *
211       * @return  The user entry DN for this bind operation, or <CODE>null</CODE> if
212       *          the bind processing has not progressed far enough to identify the
213       *          user or if the user DN could not be determined.
214       */
215      public abstract DN getUserEntryDN();
216    
217      /**
218       * Retrieves the authentication info that resulted from processing this bind
219       * operation.  It will only be valid if the bind processing was successful.
220       *
221       * @return  The authentication info that resulted from processing this bind
222       *          operation.
223       */
224      public abstract AuthenticationInfo getAuthenticationInfo();
225    
226      /**
227       * Specifies the authentication info that resulted from processing this bind
228       * operation.  This method must only be called by SASL mechanism handlers
229       * during the course of processing the {@code processSASLBind} method.
230       *
231       * @param  authInfo  The authentication info that resulted from processing
232       *                   this bind operation.
233       */
234      public abstract void setAuthenticationInfo(AuthenticationInfo authInfo);
235    
236      /**
237       * Set the user entry DN for this bind operation.
238       *
239       * @param  userEntryDN  The user entry DN for this bind operation, or
240       *                      <CODE>null</CODE> if the bind processing has not
241       *                      progressed far enough to identify the user or if
242       *                      the user DN could not be determined.
243       */
244      public abstract void setUserEntryDN(DN userEntryDN);
245    
246    
247    }