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-2013 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 continuation SASL bind result (indicating that more processing
107 * is required to complete the authentication) with the provided information.
108 *
109 * @param diagnosticMessage The diagnostic message that should be
110 * included in the response to the client. It
111 * may be {@code null} if no diagnostic message
112 * is needed.
113 * @param controls The set of controls that should be included
114 * in the response to the client. It may be
115 * {@code null} or empty if no response
116 * controls are needed.
117 * @param serverSASLCredentials The server SASL credentials that should be
118 * included in the response to the client. It
119 * may be {@code null} if no server SASL
120 * credentials are needed.
121 *
122 * @return The created continuation SASL bind result.
123 */
124 ContinuationSASLBindResult createContinuationResult(
125 final String diagnosticMessage,
126 final List<Control> controls,
127 final ASN1OctetString serverSASLCredentials);
128
129
130
131 /**
132 * Creates a failure SASL bind result with the provided information.
133 *
134 * @param authenticationFailureReason A message that explains the reason for
135 * the authentication failure. This will
136 * be recorded in the server access log
137 * but not included in the response to
138 * return to the client.
139 * @param diagnosticMessage The diagnostic message that should be
140 * included in the response to the
141 * client. It may be {@code null} if no
142 * diagnostic message is needed.
143 * @param matchedDN The matched DN that should be included
144 * in the response to the client. It may
145 * be {@code null} if no matched DN is
146 * needed.
147 * @param controls The set of controls that should be
148 * included in the response to the
149 * client. It may be {@code null} or
150 * empty if no response controls are
151 * needed.
152 * @param serverSASLCredentials The server SASL credentials that
153 * should be included in the response to
154 * the client. It may be {@code null} if
155 * no server SASL credentials are needed.
156 *
157 * @return The created failure SASL bind result.
158 */
159 FailureSASLBindResult createFailureResult(
160 final String authenticationFailureReason,
161 final String diagnosticMessage,
162 final String matchedDN,
163 final List<Control> controls,
164 final ASN1OctetString serverSASLCredentials);
165
166
167
168 /**
169 * Creates a failure SASL bind result with the provided information.
170 *
171 * @param authenticationFailureReason A message that explains the
172 * reason for the authentication
173 * failure. This will be recorded
174 * in the server access log but not
175 * included in the response to
176 * return to the client.
177 * @param diagnosticMessage The diagnostic message that
178 * should be included in the
179 * response to the client. It may
180 * be {@code null} if no diagnostic
181 * message is needed.
182 * @param matchedDN The matched DN that should be
183 * included in the response to the
184 * client. It may be {@code null}
185 * if no matched DN is needed.
186 * @param controls The set of controls that should
187 * be included in the response to
188 * the client. It may be
189 * {@code null} or empty if no
190 * response controls are needed.
191 * @param serverSASLCredentials The server SASL credentials that
192 * should be included in the
193 * response to the client. It may
194 * be {@code null} if no server
195 * SASL credentials are needed.
196 * @param unsuccessfullyAuthenticatedUserDN The DN of the user that tried
197 * to authenticate but was unable
198 * to do so successfully, if
199 * applicable.
200 *
201 * @return The created failure SASL bind result.
202 */
203 FailureSASLBindResult createFailureResult(
204 final String authenticationFailureReason,
205 final String diagnosticMessage,
206 final String matchedDN,
207 final List<Control> controls,
208 final ASN1OctetString serverSASLCredentials,
209 final String unsuccessfullyAuthenticatedUserDN);
210
211
212
213 /**
214 * Indicates whether the provided password is valid for the specified user.
215 * Note that absolutely no password policy processing will be performed. This
216 * method merely determines whether the provided password is contained in the
217 * specified user entry.
218 *
219 * @param userDN The DN of the user entry for which to make the
220 * determination. It must not be {@code null} or empty.
221 * @param password The bytes comprising the non-encoded clear-text password
222 * for which the determination is to be made. It must not
223 * be {@code null} or empty.
224 *
225 * @return {@code true} if the given password is contained in the specified
226 * user entry, or {@code false} if not.
227 *
228 * @throws LDAPException If a problem is encountered while attempting to
229 * make the determination.
230 */
231 boolean isUserPasswordValid(final String userDN,
232 final ASN1OctetString password)
233 throws LDAPException;
234
235
236
237 /**
238 * Maps the provided username to a user entry using the identity mapper
239 * associated with the SASL mechanism handler.
240 *
241 * @param username The username to be mapped to a user entry.
242 *
243 * @return The entry for the user identified by the associated identity
244 * mapper.
245 *
246 * @throws LDAPException If no identity mapper is associated with the SASL
247 * mechanism handler, or if the identity mapper cannot
248 * be used to map the username to exactly one entry.
249 */
250 Entry mapUsernameToEntry(final String username)
251 throws LDAPException;
252 }