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