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 legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2006-2008 Sun Microsystems, Inc.
025 *      Portions Copyright 2014 ForgeRock AS
026 */
027package org.opends.server.api;
028import org.forgerock.i18n.LocalizableMessage;
029
030
031
032import java.util.List;
033
034import org.opends.server.admin.std.server.PasswordGeneratorCfg;
035import org.forgerock.opendj.config.server.ConfigException;
036import org.opends.server.types.*;
037import org.forgerock.opendj.ldap.ByteString;
038
039
040/**
041 * This class defines a set of methods and structures that must be
042 * implemented by a Directory Server module that may be used to
043 * generate user passwords. The password generator is included as part
044 * of a password policy, and is used by the password modify extended
045 * operation to construct a new password for the user if that option
046 * is chosen.
047 *
048 * @param  <T>  The type of configuration handled by this password
049 *              generator.
050 */
051@org.opends.server.types.PublicAPI(
052     stability=org.opends.server.types.StabilityLevel.UNCOMMITTED,
053     mayInstantiate=false,
054     mayExtend=true,
055     mayInvoke=false)
056public abstract class PasswordGenerator
057       <T extends PasswordGeneratorCfg>
058{
059  /**
060   * Initializes this password generator based on the information in
061   * the provided configuration entry.
062   *
063   * @param  configuration  The configuration to use to initialize
064   *                        this password validator.
065   *
066   * @throws  ConfigException  If an unrecoverable problem arises in
067   *                           the process of performing the
068   *                           initialization.
069   *
070   * @throws  InitializationException  If a problem occurs during
071   *                                   initialization that is not
072   *                                   related to the server
073   *                                   configuration.
074   */
075  public abstract void initializePasswordGenerator(T configuration)
076         throws ConfigException, InitializationException;
077
078
079
080  /**
081   * Indicates whether the provided configuration is acceptable for
082   * this password generator.  It should be possible to call this
083   * method on an uninitialized password generator instance in order
084   * to determine whether the password generator would be able to use
085   * the provided configuration.
086   * <BR><BR>
087   * Note that implementations which use a subclass of the provided
088   * configuration class will likely need to cast the configuration
089   * to the appropriate subclass type.
090   *
091   * @param  configuration        The password generator configuration
092   *                              for which to make the determination.
093   * @param  unacceptableReasons  A list that may be used to hold the
094   *                              reasons that the provided
095   *                              configuration is not acceptable.
096   *
097   * @return  {@code true} if the provided configuration is acceptable
098   *          for this password generator, or {@code false} if not.
099   */
100  public boolean isConfigurationAcceptable(
101                      PasswordGeneratorCfg configuration,
102                      List<LocalizableMessage> unacceptableReasons)
103  {
104    // This default implementation does not perform any special
105    // validation.  It should be overridden by password generator
106    // implementations that wish to perform more detailed validation.
107    return true;
108  }
109
110
111
112  /**
113   * Performs any finalization work that may be necessary when this
114   * password generator is taken out of service.
115   */
116  public void finalizePasswordGenerator()
117  {
118    // No action is performed by default.
119  }
120
121
122
123  /**
124   * Generates a password for the user whose account is contained in
125   * the specified entry.
126   *
127   * @param  userEntry  The entry for the user for whom the password
128   *                    is to be generated.
129   *
130   * @return  The password that has been generated for the user.
131   *
132   * @throws  DirectoryException  If a problem occurs while attempting
133   *                              to generate the password.
134   */
135  public abstract ByteString generatePassword(Entry userEntry)
136         throws DirectoryException;
137}
138