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