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