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.SASLMechanismHandlerCfg;
035    import org.opends.server.config.ConfigException;
036    import org.opends.server.core.BindOperation;
037    import org.opends.server.types.InitializationException;
038    
039    
040    
041    /**
042     * This class defines the set of methods and structures that must be
043     * implemented by a Directory Server module that implements the
044     * functionality required for one or more SASL mechanisms.
045     *
046     * @param  <T>  The type of configuration handled by this SASL
047     *              mechanism handler.
048     */
049    @org.opends.server.types.PublicAPI(
050         stability=org.opends.server.types.StabilityLevel.VOLATILE,
051         mayInstantiate=false,
052         mayExtend=true,
053         mayInvoke=false)
054    public abstract class SASLMechanismHandler
055           <T extends SASLMechanismHandlerCfg>
056    {
057      /**
058       * Initializes this SASL mechanism handler based on the information
059       * in the provided configuration entry.  It should also register
060       * itself with the Directory Server for the particular kinds of SASL
061       * mechanisms that it will process.
062       *
063       * @param  configuration  The configuration to use to initialize
064       *                        this SASL mechanism handler.
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 initializeSASLMechanismHandler(T configuration)
076             throws ConfigException, InitializationException;
077    
078    
079    
080      /**
081       * Indicates whether the provided configuration is acceptable for
082       * this SASL mechanism handler.  It should be possible to call this
083       * method on an uninitialized SASL mechanism handler instance in
084       * order to determine whether the SASL mechanism handler would be
085       * able to use 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 SASL mechanism handler
092       *                              configuration for which to make the
093       *                              determination.
094       * @param  unacceptableReasons  A list that may be used to hold the
095       *                              reasons that the provided
096       *                              configuration is not acceptable.
097       *
098       * @return  {@code true} if the provided configuration is acceptable
099       *          for this SASL mechanism handler, or {@code false} if
100       *          not.
101       */
102      public boolean isConfigurationAcceptable(
103                          SASLMechanismHandlerCfg configuration,
104                          List<Message> unacceptableReasons)
105      {
106        // This default implementation does not perform any special
107        // validation.  It should be overridden by SASL mechanism handler
108        // implementations that wish to perform more detailed validation.
109        return true;
110      }
111    
112    
113    
114      /**
115       * Performs any finalization that may be necessary for this SASL
116       * mechanism handler.  By default, no finalization is performed.
117       */
118      public void finalizeSASLMechanismHandler()
119      {
120        // No implementation is required by default.
121      }
122    
123    
124    
125      /**
126       * Processes the SASL bind operation.  SASL mechanism
127       * implementations must ensure that the following actions are taken
128       * during the processing of this method:
129       * <UL>
130       *   <LI>The {@code BindOperation.setResultCode} method must be used
131       *       to set the appropriate result code.</LI>
132       *   <LI>If the SASL processing gets far enough to be able to map
133       *       the request to a user entry (regardless of whether the
134       *       authentication is ultimately successful), then this method
135       *       must call the {@code BindOperation.setSASLAuthUserEntry}
136       *       method to provide it with the entry for the user that
137       *       attempted to authenticate.</LI>
138       *   <LI>If the bind processing was successful, then the
139       *       {@code BindOperation.setAuthenticationInfo} method must be
140       *       used to set the authentication info for the bind
141       *       operation.</LI>
142       *   <LI>If the bind processing was not successful, then the
143       *       {@code BindOperation.setAuthFailureReason} method should be
144       *       used to provide a message explaining why the authentication
145       *       failed.</LI>
146       * </UL>
147       *
148       * @param  bindOperation  The SASL bind operation to be processed.
149       */
150      public abstract void processSASLBind(BindOperation bindOperation);
151    
152    
153    
154      /**
155       * Indicates whether the specified SASL mechanism is password-based
156       * or uses some other form of credentials (e.g., an SSL client
157       * certificate or Kerberos ticket).
158       *
159       * @param  mechanism  The name of the mechanism for which to make
160       *                    the determination.  This will only be invoked
161       *                    with names of mechanisms for which this
162       *                    handler has previously registered.
163       *
164       * @return  {@code true} if this SASL mechanism is password-based,
165       *          or {@code false} if it uses some other form of
166       *          credentials.
167       */
168      public abstract boolean isPasswordBased(String mechanism);
169    
170    
171    
172      /**
173       * Indicates whether the specified SASL mechanism should be
174       * considered secure (i.e., it does not expose the authentication
175       * credentials in a manner that is useful to a third-party observer,
176       * and other aspects of the authentication are generally secure).
177       *
178       * @param  mechanism  The name of the mechanism for which to make
179       *                    the determination.  This will only be invoked
180       *                    with names of mechanisms for which this
181       *                    handler has previously registered.
182       *
183       * @return  {@code true} if this SASL mechanism should be considered
184       *          secure, or {@code false} if not.
185       */
186      public abstract boolean isSecure(String mechanism);
187    }
188