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