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.AccessControlHandlerCfg;
035    import org.opends.server.config.ConfigException;
036    import org.opends.server.core.*;
037    import org.opends.server.types.*;
038    import org.opends.server.workflowelement.localbackend.*;
039    
040    
041    /**
042     * This class defines the set of methods and structures that must be
043     * implemented by a Directory Server access control handler.  All
044     * methods in this class should take the entire request into account
045     * when making the determination, including any request controls that
046     * might have been provided.
047     *
048     * @param  <T>  The type of access control configuration handled by
049     *              this access control provider implementation.
050     */
051    @org.opends.server.types.PublicAPI(
052         stability=org.opends.server.types.StabilityLevel.VOLATILE,
053         mayInstantiate=false,
054         mayExtend=true,
055         mayInvoke=false)
056    public abstract class AccessControlHandler
057                          <T extends AccessControlHandlerCfg>
058    {
059      /**
060       * Initializes the access control handler implementation based on
061       * the information in the provided configuration entry.
062       *
063       * @param  configuration  The configuration object that contains the
064       *                        information to use to initialize this
065       *                        access control handler.
066       *
067       * @throws  ConfigException  If an unrecoverable problem arises in
068       *                           the process of performing the
069       *                           initialization.
070       *
071       * @throws  InitializationException  If a problem occurs during
072       *                                   initialization that is not
073       *                                   related to the server
074       *                                   configuration.
075       */
076      public abstract void initializeAccessControlHandler(T configuration)
077    
078             throws ConfigException, InitializationException;
079    
080    
081    
082      /**
083       * Indicates whether the provided configuration is acceptable for
084       * this access control handler.  It should be possible to call this
085       * method on an uninitialized access control handler instance in
086       * order to determine whether the handler would be able to use the
087       * provided configuration.
088       * <BR><BR>
089       * Note that implementations which use a subclass of the provided
090       * configuration class will likely need to cast the configuration
091       * to the appropriate subclass type.
092       *
093       * @param  configuration        The access control handler
094       *                              configuration for which to make the
095       *                              determination.
096       * @param  unacceptableReasons  A list that may be used to hold the
097       *                              reasons that the provided
098       *                              configuration is not acceptable.
099       *
100       * @return  {@code true} if the provided configuration is acceptable
101       *          for this access control handler, or {@code false} if
102       *          not.
103       */
104      public boolean isConfigurationAcceptable(
105                          AccessControlHandlerCfg configuration,
106                          List<Message> unacceptableReasons)
107      {
108        // This default implementation does not perform any special
109        // validation.  It should be overridden by access control handler
110        // implementations that wish to perform more detailed validation.
111        return true;
112      }
113    
114    
115    
116      /**
117       * Performs any necessary finalization for the access control
118       * handler implementation. This will be called just after the
119       * handler has been deregistered with the server but before it has
120       * been unloaded.
121       */
122      public abstract void finalizeAccessControlHandler();
123    
124    
125    
126      /**
127       * Indicates whether the provided add operation is allowed based on
128       * the access control configuration.  This method should not alter
129       * the provided add operation in any way.
130       *
131       * @param  addOperation  The operation for which to make the
132       *                       determination.
133       *
134       * @return  {@code true} if the operation should be allowed by the
135       *          access control configuration, or {@code false} if not.
136       */
137      public abstract boolean isAllowed(LocalBackendAddOperation
138                                             addOperation);
139    
140    
141      /**
142       * Indicates whether the provided control is allowed based on
143       * the access control configuration and the specified
144       * operation. This method should not alter the provided
145       * operation in any way.
146       *
147       * @param  dn  A DN that can be used in the access determination.
148       *
149       * @param  op  The operation to use in the
150       *                       determination.
151       *
152       * @param control The control for which to make the determination.
153       *
154       * @return  {@code true} if the control should be allowed by the
155       *          access control configuration, or {@code false} if not.
156       */
157      public abstract boolean isAllowed(DN dn, Operation  op,
158                                        Control control);
159    
160    
161    
162      /**
163       * Indicates whether the provided bind operation is allowed based on
164       * the access control configuration.  This method should not alter
165       * the provided bind operation in any way.
166       *
167       * @param  bindOperation  The operation for which to make the
168       *                        determination.
169       *
170       * @return  {@code true} if the operation should be allowed by the
171       *          access control configuration, or {@code false} if not.
172       */
173      public abstract boolean isAllowed(LocalBackendBindOperation
174                                             bindOperation);
175    
176    
177    
178      /**
179       * Indicates whether the provided compare operation is allowed based
180       * on the access control configuration.  This method should not
181       * alter the provided compare operation in any way.
182       *
183       * @param  compareOperation  The operation for which to make the
184       *                           determination.
185       *
186       * @return  {@code true} if the operation should be allowed by the
187       *          access control configuration, or {@code false} if not.
188       */
189      public abstract boolean isAllowed(LocalBackendCompareOperation
190          compareOperation);
191    
192    
193    
194      /**
195       * Indicates whether the provided delete operation is allowed based
196       * on the access control configuration.  This method should not
197       * alter the provided delete operation in any way.
198       *
199       * @param  deleteOperation  The operation for which to make the
200       *                          determination.
201       *
202       * @return  {@code true} if the operation should be allowed by the
203       *          access control configuration, or {@code false} if not.
204       */
205      public abstract boolean isAllowed(LocalBackendDeleteOperation
206                                             deleteOperation);
207    
208    
209    
210      /**
211       * Indicates whether the provided extended operation is allowed
212       * based on the access control configuration.  This method should
213       * not alter the provided extended operation in any way.
214       *
215       * @param  extendedOperation  The operation for which to make the
216       *                            determination.
217       *
218       * @return  {@code true} if the operation should be allowed by the
219       *          access control configuration, or {@code false} if not.
220       */
221      public abstract boolean isAllowed(ExtendedOperation
222                                             extendedOperation);
223    
224    
225    
226      /**
227       * Indicates whether the provided modify operation is allowed based
228       * on the access control configuration.  This method should not
229       * alter the provided modify operation in any way.
230       *
231       * @param  modifyOperation  The operation for which to make the
232       *                          determination.
233       *
234       * @return  {@code true} if the operation should be allowed by the
235       *          access control configuration, or {@code false} if not.
236       */
237      public abstract boolean isAllowed(LocalBackendModifyOperation
238                                             modifyOperation);
239    
240    
241    
242      /**
243       * Indicates whether the provided modify DN operation is allowed
244       * based on the access control configuration.  This method should
245       * not alter the provided modify DN operation in any way.
246       *
247       * @param  modifyDNOperation  The operation for which to make the
248       *                            determination.
249       *
250       * @return  {@code true} if the operation should be allowed by the
251       *          access control configuration, or {@code false} if not.
252       */
253      public abstract boolean isAllowed(LocalBackendModifyDNOperation
254                                             modifyDNOperation);
255    
256    
257    
258      /**
259       * Indicates whether the provided search operation is allowed based
260       * on the access control configuration.  This method may only alter
261       * the provided search operation in order to add an opaque block of
262       * data to it that will be made available for use in determining
263       * whether matching search result entries or search result
264       * references may be allowed.
265       *
266       * @param  searchOperation  The operation for which to make the
267       *                          determination.
268       *
269       * @return  {@code true} if the operation should be allowed by the
270       *          access control configuration, or {@code false} if not.
271       */
272      public abstract boolean isAllowed(LocalBackendSearchOperation
273                                             searchOperation);
274    
275    
276    
277      /**
278       * Indicates whether the provided search result entry may be sent to
279       * the client. Implementations <b>must not under any
280       * circumstances</b> modify the search entry in any way.
281       *
282       * @param  searchOperation  The search operation with which the
283       *                          provided entry is associated.
284       * @param  searchEntry      The search result entry for which to
285       *                          make the determination.
286       *
287       * @return  {@code true} if the access control configuration allows
288       *          the entry to be returned to the client, or {@code false}
289       *          if not.
290       */
291      public abstract boolean maySend(SearchOperation searchOperation,
292                                      SearchResultEntry searchEntry);
293    
294    
295    
296      /**
297       * Filter the contents of the provided entry such that it no longer
298       * contains any attributes or values that the client is not
299       * permitted to access.
300       *
301       * @param searchOperation The search operation with which the
302       *                        provided entry is associated.
303       * @param searchEntry     The search result entry to be filtered.
304       *
305       * @return  Returns the entry with filtered attributes and values
306       *          removed.
307       */
308      public abstract SearchResultEntry
309                           filterEntry(SearchOperation searchOperation,
310                                       SearchResultEntry searchEntry);
311    
312    
313    
314      /**
315       * Indicates whether the provided search result reference may be
316       * sent to the client based on the access control configuration.
317       *
318       * @param  dn         A DN that can be used in the access
319       *                    determination.
320       *
321       * @param  searchOperation  The search operation with which the
322       *                          provided reference is associated.
323       * @param  searchReference  The search result reference for which to
324       *                          make the determination.
325       *
326       * @return  {@code true} if the access control configuration allows
327       *          the reference to be returned to the client, or
328       *          {@code false} if not.
329       */
330      public abstract boolean maySend(DN dn,
331                                 SearchOperation searchOperation,
332                                 SearchResultReference searchReference);
333    
334    }
335