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