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 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
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 * docs/licenses/cddl.txt. 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 2012-2014 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.ds.types;
028
029
030
031 import java.util.List;
032
033 import com.unboundid.asn1.ASN1OctetString;
034 import com.unboundid.directory.sdk.common.types.Entry;
035 import com.unboundid.ldap.sdk.Control;
036 import com.unboundid.ldap.sdk.LDAPException;
037 import com.unboundid.util.NotExtensible;
038 import com.unboundid.util.ThreadSafety;
039 import com.unboundid.util.ThreadSafetyLevel;
040
041
042
043 /**
044 * This interface provides methods that may be used to construct SASL bind
045 * result objects.
046 */
047 @NotExtensible()
048 @ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
049 public interface SASLBindResultFactory
050 {
051 /**
052 * Creates a success SASL bind result in which the authentication and
053 * authorization user identities are the same, and no diagnostic message,
054 * controls, or server SASL credentials need to be returned.
055 *
056 * @param authenticatedUserDN The DN of the user that has been
057 * authenticated. It may be {@code null} if the
058 * resulting authentication was anonymous.
059 *
060 * @return The created success SASL bind result.
061 */
062 SuccessSASLBindResult createSuccessResult(final String authenticatedUserDN);
063
064
065
066 /**
067 * Creates a success SASL bind result with the provided information.
068 *
069 * @param authenticatedUserDN The DN of the user that has been
070 * authenticated. It may be empty or
071 * {@code null} if the resulting authentication
072 * was anonymous.
073 * @param authorizedUserDN The DN of the user that should be used as
074 * the authorization identity for subsequent
075 * operations requested on the connection. In
076 * most cases, it should be the same as the
077 * authenticated user DN, but it may be
078 * different if an alternate authorization
079 * identity was specified. It may be empty or
080 * {@code null} if the authorization identity
081 * should be that of the anonymous user.
082 * @param diagnosticMessage The diagnostic message that should be
083 * included in the response to the client. It
084 * may be {@code null} if no diagnostic message
085 * is needed.
086 * @param controls The set of controls that should be included
087 * in the response to the client. It may be
088 * {@code null} or empty if no response
089 * controls are needed.
090 * @param serverSASLCredentials The server SASL credentials that should be
091 * included in the response to the client. It
092 * may be {@code null} if no server SASL
093 * credentials are needed.
094 *
095 * @return The created success SASL bind result.
096 */
097 SuccessSASLBindResult createSuccessResult(final String authenticatedUserDN,
098 final String authorizedUserDN,
099 final String diagnosticMessage,
100 final List<Control> controls,
101 final ASN1OctetString serverSASLCredentials);
102
103
104
105 /**
106 * Creates a success SASL bind result with the provided information.
107 *
108 * @param authenticatedUserDN The DN of the user that has been
109 * authenticated. It may be empty or
110 * {@code null} if the resulting authentication
111 * was anonymous.
112 * @param authorizedUserDN The DN of the user that should be used as
113 * the authorization identity for subsequent
114 * operations requested on the connection. In
115 * most cases, it should be the same as the
116 * authenticated user DN, but it may be
117 * different if an alternate authorization
118 * identity was specified. It may be empty or
119 * {@code null} if the authorization identity
120 * should be that of the anonymous user.
121 * @param diagnosticMessage The diagnostic message that should be
122 * included in the response to the client. It
123 * may be {@code null} if no diagnostic message
124 * is needed.
125 * @param controls The set of controls that should be included
126 * in the response to the client. It may be
127 * {@code null} or empty if no response
128 * controls are needed.
129 * @param serverSASLCredentials The server SASL credentials that should be
130 * included in the response to the client. It
131 * may be {@code null} if no server SASL
132 * credentials are needed.
133 * @param passwordUsed The plaintext password that was used to
134 * authenticate. This may be {@code null} if
135 * the associated SASL mechanism is not
136 * password-based or if the plaintext password
137 * is not available.
138 *
139 * @return The created success SASL bind result.
140 */
141 SuccessSASLBindResult createSuccessResult(final String authenticatedUserDN,
142 final String authorizedUserDN,
143 final String diagnosticMessage,
144 final List<Control> controls,
145 final ASN1OctetString serverSASLCredentials,
146 final ASN1OctetString passwordUsed);
147
148
149
150 /**
151 * Creates a continuation SASL bind result (indicating that more processing
152 * is required to complete the authentication) with the provided information.
153 *
154 * @param diagnosticMessage The diagnostic message that should be
155 * included in the response to the client. It
156 * may be {@code null} if no diagnostic message
157 * is needed.
158 * @param controls The set of controls that should be included
159 * in the response to the client. It may be
160 * {@code null} or empty if no response
161 * controls are needed.
162 * @param serverSASLCredentials The server SASL credentials that should be
163 * included in the response to the client. It
164 * may be {@code null} if no server SASL
165 * credentials are needed.
166 *
167 * @return The created continuation SASL bind result.
168 */
169 ContinuationSASLBindResult createContinuationResult(
170 final String diagnosticMessage,
171 final List<Control> controls,
172 final ASN1OctetString serverSASLCredentials);
173
174
175
176 /**
177 * Creates a failure SASL bind result with the provided information.
178 *
179 * @param authenticationFailureReason A message that explains the reason for
180 * the authentication failure. This will
181 * be recorded in the server access log
182 * but not included in the response to
183 * return to the client.
184 * @param diagnosticMessage The diagnostic message that should be
185 * included in the response to the
186 * client. It may be {@code null} if no
187 * diagnostic message is needed.
188 * @param matchedDN The matched DN that should be included
189 * in the response to the client. It may
190 * be {@code null} if no matched DN is
191 * needed.
192 * @param controls The set of controls that should be
193 * included in the response to the
194 * client. It may be {@code null} or
195 * empty if no response controls are
196 * needed.
197 * @param serverSASLCredentials The server SASL credentials that
198 * should be included in the response to
199 * the client. It may be {@code null} if
200 * no server SASL credentials are needed.
201 *
202 * @return The created failure SASL bind result.
203 */
204 FailureSASLBindResult createFailureResult(
205 final String authenticationFailureReason,
206 final String diagnosticMessage,
207 final String matchedDN,
208 final List<Control> controls,
209 final ASN1OctetString serverSASLCredentials);
210
211
212
213 /**
214 * Creates a failure SASL bind result with the provided information.
215 *
216 * @param authenticationFailureReason A message that explains the
217 * reason for the authentication
218 * failure. This will be recorded
219 * in the server access log but not
220 * included in the response to
221 * return to the client.
222 * @param diagnosticMessage The diagnostic message that
223 * should be included in the
224 * response to the client. It may
225 * be {@code null} if no diagnostic
226 * message is needed.
227 * @param matchedDN The matched DN that should be
228 * included in the response to the
229 * client. It may be {@code null}
230 * if no matched DN is needed.
231 * @param controls The set of controls that should
232 * be included in the response to
233 * the client. It may be
234 * {@code null} or empty if no
235 * response controls are needed.
236 * @param serverSASLCredentials The server SASL credentials that
237 * should be included in the
238 * response to the client. It may
239 * be {@code null} if no server
240 * SASL credentials are needed.
241 * @param unsuccessfullyAuthenticatedUserDN The DN of the user that tried
242 * to authenticate but was unable
243 * to do so successfully, if
244 * applicable.
245 *
246 * @return The created failure SASL bind result.
247 */
248 FailureSASLBindResult createFailureResult(
249 final String authenticationFailureReason,
250 final String diagnosticMessage,
251 final String matchedDN,
252 final List<Control> controls,
253 final ASN1OctetString serverSASLCredentials,
254 final String unsuccessfullyAuthenticatedUserDN);
255
256
257
258 /**
259 * Indicates whether the provided password is valid for the specified user.
260 * Note that absolutely no password policy processing will be performed. This
261 * method merely determines whether the provided password is contained in the
262 * specified user entry.
263 *
264 * @param userDN The DN of the user entry for which to make the
265 * determination. It must not be {@code null} or empty.
266 * @param password The bytes comprising the non-encoded clear-text password
267 * for which the determination is to be made. It must not
268 * be {@code null} or empty.
269 *
270 * @return {@code true} if the given password is contained in the specified
271 * user entry, or {@code false} if not.
272 *
273 * @throws LDAPException If a problem is encountered while attempting to
274 * make the determination.
275 */
276 boolean isUserPasswordValid(final String userDN,
277 final ASN1OctetString password)
278 throws LDAPException;
279
280
281
282 /**
283 * Maps the provided username to a user entry using the identity mapper
284 * associated with the SASL mechanism handler.
285 *
286 * @param username The username to be mapped to a user entry.
287 *
288 * @return The entry for the user identified by the associated identity
289 * mapper.
290 *
291 * @throws LDAPException If no identity mapper is associated with the SASL
292 * mechanism handler, or if the identity mapper cannot
293 * be used to map the username to exactly one entry.
294 */
295 Entry mapUsernameToEntry(final String username)
296 throws LDAPException;
297 }