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.api;
028 import org.opends.messages.Message;
029
030
031
032 import java.util.List;
033
034 import org.opends.server.admin.std.server.PasswordStorageSchemeCfg;
035 import org.opends.server.config.ConfigException;
036 import org.opends.server.types.ByteString;
037 import org.opends.server.types.DirectoryException;
038 import org.opends.server.types.InitializationException;
039
040
041
042 /**
043 * This class defines the set of methods and structures that must be
044 * implemented by a Directory Server module that implements a password
045 * storage scheme. Each subclass may only implement a single password
046 * storage scheme type.
047 *
048 * @param <T> The type of configuration handled by this
049 * password storage scheme
050 */
051 @org.opends.server.types.PublicAPI(
052 stability=org.opends.server.types.StabilityLevel.UNCOMMITTED,
053 mayInstantiate=false,
054 mayExtend=true,
055 mayInvoke=false)
056 public abstract class
057 PasswordStorageScheme <T extends PasswordStorageSchemeCfg>
058 {
059 /**
060 * Initializes this password storage scheme handler based on the
061 * information in the provided configuration entry. It should also
062 * register itself with the Directory Server for the particular
063 * storage scheme that it will manage.
064 *
065 * @param configuration The configuration entry that contains the
066 * information to use to initialize this
067 * password storage scheme handler.
068 *
069 * @throws ConfigException If an unrecoverable problem arises in
070 * the process of performing the
071 * initialization.
072 *
073 * @throws InitializationException If a problem occurs during
074 * initialization that is not
075 * related to the server
076 * configuration.
077 */
078 public abstract void initializePasswordStorageScheme(
079 T configuration)
080 throws ConfigException, InitializationException;
081
082
083
084 /**
085 * Indicates whether the provided configuration is acceptable for
086 * this password storage scheme. It should be possible to call this
087 * method on an uninitialized password storage scheme instance in
088 * order to determine whether the password storage scheme would be
089 * able to use the provided configuration.
090 * <BR><BR>
091 * Note that implementations which use a subclass of the provided
092 * configuration class will likely need to cast the configuration
093 * to the appropriate subclass type.
094 *
095 * @param configuration The password storage scheme
096 * configuration for which to make the
097 * determination.
098 * @param unacceptableReasons A list that may be used to hold the
099 * reasons that the provided
100 * configuration is not acceptable.
101 *
102 * @return {@code true} if the provided configuration is acceptable
103 * for this password storage scheme, or {@code false} if
104 * not.
105 */
106 public boolean isConfigurationAcceptable(
107 PasswordStorageSchemeCfg configuration,
108 List<Message> unacceptableReasons)
109 {
110 // This default implementation does not perform any special
111 // validation. It should be overridden by password storage scheme
112 // implementations that wish to perform more detailed validation.
113 return true;
114 }
115
116
117
118 /**
119 * Performs any necessary finalization that might be required when
120 * this password storage scheme is no longer needed (e.g., the
121 * scheme is disabled or the server is shutting down).
122 */
123 public void finalizePasswordStorageScheme()
124 {
125 // No implementation required by default.
126 }
127
128
129
130 /**
131 * Retrieves the name of the password storage scheme provided by
132 * this handler.
133 *
134 * @return The name of the password storage scheme provided by this
135 * handler.
136 */
137 public abstract String getStorageSchemeName();
138
139
140
141 /**
142 * Encodes the provided plaintext password for this storage scheme,
143 * without the name of the associated scheme. Note that the
144 * provided plaintext password should not be altered in any way.
145 *
146 * @param plaintext The plaintext version of the password.
147 *
148 * @return The password that has been encoded using this storage
149 * scheme.
150 *
151 * @throws DirectoryException If a problem occurs while
152 * processing.
153 */
154 public abstract ByteString encodePassword(ByteString plaintext)
155 throws DirectoryException;
156
157
158
159 /**
160 * Encodes the provided plaintext password for this storage scheme,
161 * prepending the name of the scheme in curly braces. Note that the
162 * provided plaintext password should not be altered in any way.
163 *
164 * @param plaintext The plaintext version of the password.
165 *
166 * @return The encoded password, including the name of the storage
167 * scheme.
168 *
169 * @throws DirectoryException If a problem occurs while
170 * processing.
171 */
172 public abstract ByteString encodePasswordWithScheme(
173 ByteString plaintext)
174 throws DirectoryException;
175
176
177
178
179 /**
180 * Indicates whether the provided plaintext password included in a
181 * bind request matches the given stored value. The provided stored
182 * value should not include the scheme name in curly braces.
183 *
184 * @param plaintextPassword The plaintext password provided by the
185 * user as part of a simple bind attempt.
186 * @param storedPassword The stored password to compare against
187 * the provided plaintext password.
188 *
189 * @return {@code true} if the provided plaintext password matches
190 * the provided stored password, or {@code false} if not.
191 */
192 public abstract boolean passwordMatches(
193 ByteString plaintextPassword,
194 ByteString storedPassword);
195
196
197
198 /**
199 * Indicates whether this password storage scheme supports the
200 * ability to interact with values using the authentication password
201 * syntax defined in RFC 3112.
202 *
203 * @return {@code true} if this password storage scheme supports
204 * the ability to interact with values using the
205 * authentication password syntax, or {@code false} if it
206 * does not.
207 */
208 public abstract boolean supportsAuthPasswordSyntax();
209
210
211
212 /**
213 * Retrieves the scheme name that should be used with this password
214 * storage scheme when it is used in the context of the
215 * authentication password syntax. This default implementation will
216 * return the same value as the {@code getStorageSchemeName} method.
217 *
218 * @return The scheme name that should be used with this password
219 * storage scheme when it is used in the context of the
220 * authentication password syntax.
221 */
222 public String getAuthPasswordSchemeName()
223 {
224 return getStorageSchemeName();
225 }
226
227
228
229 /**
230 * Encodes the provided plaintext password for this storage scheme
231 * using the authentication password syntax defined in RFC 3112.
232 * Note that the provided plaintext password should not be altered
233 * in any way.
234 *
235 * @param plaintext The plaintext version of the password.
236 *
237 * @return The password that has been encoded in the authentication
238 * password syntax.
239 *
240 * @throws DirectoryException If a problem occurs while processing
241 * of if this storage scheme does not
242 * support the authentication password
243 * syntax.
244 */
245 public abstract ByteString encodeAuthPassword(ByteString plaintext)
246 throws DirectoryException;
247
248
249
250 /**
251 * Indicates whether the provided plaintext password matches the
252 * encoded password using the authentication password syntax with
253 * the given authInfo and authValue components.
254 *
255 * @param plaintextPassword The plaintext password provided by the
256 * user.
257 * @param authInfo The authInfo component of the password
258 * encoded in the authentication password
259 * syntax.
260 * @param authValue The authValue component of the
261 * password encoded in the authentication
262 * password syntax.
263 *
264 * @return {@code true} if the provided plaintext password matches
265 * the encoded password according to the authentication
266 * password info syntax, or {@code false} if it does not or
267 * this storage scheme does not support the authentication
268 * password syntax.
269 */
270 public abstract boolean authPasswordMatches(
271 ByteString plaintextPassword,
272 String authInfo, String authValue);
273
274
275
276 /**
277 * Indicates whether this storage scheme is reversible (i.e., it is
278 * possible to obtain the original plaintext value from the stored
279 * password).
280 *
281 * @return {@code true} if this is a reversible password storage
282 * scheme, or {@code false} if it is not.
283 */
284 public abstract boolean isReversible();
285
286
287
288 /**
289 * Retrieves the original plaintext value for the provided stored
290 * password. Note that this should only be called if
291 * {@code isReversible} returns {@code true}.
292 *
293 * @param storedPassword The password for which to obtain the
294 * plaintext value. It should not include
295 * the scheme name in curly braces.
296 *
297 * @return The plaintext value for the provided stored password.
298 *
299 * @throws DirectoryException If it is not possible to obtain the
300 * plaintext value for the provided
301 * stored password.
302 */
303 public abstract ByteString getPlaintextValue(
304 ByteString storedPassword)
305 throws DirectoryException;
306
307
308
309 /**
310 * Retrieves the original plaintext value for the provided password
311 * stored in the authPassword syntax. Note that this should only be
312 * called if {@code isReversible} returns {@code true}.
313 *
314 * @param authInfo The authInfo component of the password encoded
315 * in the authentication password syntax.
316 * @param authValue The authValue component of the password
317 * encoded in the authentication password syntax.
318 *
319 * @return The plaintext value for the provided stored password.
320 *
321 * @throws DirectoryException If it is not possible to obtain the
322 * plaintext value for the provided
323 * stored password, or if this storage
324 * scheme does not support the
325 * authPassword syntax..
326 */
327 public abstract ByteString getAuthPasswordPlaintextValue(
328 String authInfo, String authValue)
329 throws DirectoryException;
330
331
332
333 /**
334 * Indicates whether this password storage scheme should be
335 * considered "secure". If the encoding used for this scheme does
336 * not obscure the value at all, or if it uses a method that is
337 * trivial to reverse (e.g., base64), then it should not be
338 * considered secure.
339 * <BR><BR>
340 * This may be used to determine whether a password may be included
341 * in a set of search results, including the possibility of
342 * overriding access controls in the case that access controls would
343 * allow the password to be returned but the password is considered
344 * too insecure to reveal.
345 *
346 * @return {@code false} if it may be trivial to discover the
347 * original plain-text password from the encoded form, or
348 * {@code true} if the scheme offers sufficient protection
349 * that revealing the encoded password will not easily
350 * reveal the corresponding plain-text value.
351 */
352 public abstract boolean isStorageSchemeSecure();
353 }
354