Dereference support

This adds support for the newly proposed LDAP Dereference feature (not to
be confused with alias dereferencing).  The details of the proposed feature
can be found here:
http://www.openldap.org/devel/cvsweb.cgi/~checkout~/doc/drafts/draft-masarati-ldap-deref-xx.txt
This adds a new deref plugin to the directory server.  This is a pre op search
plugin.  In order to allow the plugin to rewrite the controls sent back with
each entry, I changed the way pre-search and pre-entry plugins work.  They now
have the ability to alter the entry and controls just before being sent back
to the client.
This plugin does not currently support internal operations.  It should be easy
to add a call to register the plugin for internal ops if we need to do that.
The code supports real, computed (e.g. memberOf), and virtual attributes
both as the attibute to dereference and in the list of attributes to return
from each dereferenced entry.  This will allow us to use attributes such as
nsRole as the derefattr.
Tested on RHEL5 x86_64 with various openldap 2.4.15+ and Net::LDAP clients.
valgrind output is clean

7 files changed, 949 insertions, 29 deletions

diff --git a/ldap/ldif/template-dse.ldif.in b/ldap/ldif/template-dse.ldif.in
index c2ac588f..1dfd9d56 100644
--- a/ldap/ldif/template-dse.ldif.in
+++ b/ldap/ldif/template-dse.ldif.in
@@ -632,6 +632,18 @@ nsslapd-pluginarg3: ,
 nsslapd-pluginarg4: %ds_suffix%
 nsslapd-plugin-depends-on-type: database
 
+dn: cn=deref,cn=plugins,cn=config
+objectclass: top
+objectclass: nsSlapdPlugin
+objectclass: extensibleObject
+objectclass: nsContainer
+cn: deref
+nsslapd-pluginpath: libderef-plugin
+nsslapd-plugininitfunc: deref_init
+nsslapd-plugintype: preoperation
+nsslapd-pluginenabled: on
+nsslapd-plugin-depends-on-type: database
+
 dn: cn=Internationalization Plugin,cn=plugins,cn=config
 objectclass: top
 objectclass: nsSlapdPlugin
diff --git a/ldap/servers/plugins/deref/deref.c b/ldap/servers/plugins/deref/deref.c
new file mode 100644
index 00000000..a2428496
--- /dev/null
+++ b/ldap/servers/plugins/deref/deref.c
@@ -0,0 +1,797 @@
+/** BEGIN COPYRIGHT BLOCK
+ * This Program is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation; version 2 of the License.
+ *
+ * This Program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this Program; if not, write to the Free Software Foundation, Inc., 59 Temple
+ * Place, Suite 330, Boston, MA 02111-1307 USA.
+ *
+ * In addition, as a special exception, Red Hat, Inc. gives You the additional
+ * right to link the code of this Program with code not covered under the GNU
+ * General Public License ("Non-GPL Code") and to distribute linked combinations
+ * including the two, subject to the limitations in this paragraph. Non-GPL Code
+ * permitted under this exception must only link to the code of this Program
+ * through those well defined interfaces identified in the file named EXCEPTION
+ * found in the source code files (the "Approved Interfaces"). The files of
+ * Non-GPL Code may instantiate templates or use macros or inline functions from
+ * the Approved Interfaces without causing the resulting work to be covered by
+ * the GNU General Public License. Only Red Hat, Inc. may make changes or
+ * additions to the list of Approved Interfaces. You must obey the GNU General
+ * Public License in all respects for all of the Program code and other code used
+ * in conjunction with the Program except the Non-GPL Code covered by this
+ * exception. If you modify this file, you may extend this exception to your
+ * version of the file, but you are not obligated to do so. If you do not wish to
+ * provide this exception without modification, you must delete this exception
+ * statement from your version and license this file solely under the GPL without
+ * exception.
+ *
+ *
+ * Copyright (C) 2009 Red Hat, Inc.
+ * All rights reserved.
+ * END COPYRIGHT BLOCK **/
+
+#ifdef HAVE_CONFIG_H
+#  include <config.h>
+#endif
+
+/*
+ * Dereference plug-in
+ */
+#include <string.h>
+#include "deref.h"
+#include "dirlite_strings.h"
+#include "dirver.h"
+#include <nspr.h>
+
+#ifndef DN_SYNTAX_OID
+#define DN_SYNTAX_OID "1.3.6.1.4.1.1466.115.121.1.12"
+#endif
+
+/*
+ * Plug-in globals
+ */
+static void *_PluginID = NULL;
+static char *_PluginDN = NULL;
+static int g_plugin_started = 0;
+
+static Slapi_PluginDesc pdesc = { DEREF_FEATURE_DESC,
+                                  PLUGIN_MAGIC_VENDOR_STR,
+                                  PRODUCTTEXT,
+                                  DEREF_PLUGIN_DESC };
+
+/*
+ * Plug-in management functions
+ */
+int deref_init(Slapi_PBlock * pb);
+static int deref_start(Slapi_PBlock * pb);
+static int deref_close(Slapi_PBlock * pb);
+
+/*
+ * Operation callbacks (where the real work is done)
+ */
+static int deref_pre_search(Slapi_PBlock * pb);
+static int deref_pre_entry(Slapi_PBlock *pb);
+
+typedef struct _DerefSpec {
+    char *derefattr; /* attribute to deref - must have DN syntax */
+    char **attrs; /* attributes to return from dereferenced entry */
+} DerefSpec;
+
+static DerefSpec*
+new_DerefSpec(char *derefattr, char **attrs) {
+    DerefSpec *spec = (DerefSpec *)slapi_ch_calloc(1, sizeof(DerefSpec));
+    spec->derefattr = derefattr;
+    spec->attrs = attrs;
+
+    return spec;
+}
+
+static void
+delete_DerefSpec(DerefSpec **spec)
+{
+    if (spec && *spec) {
+        slapi_ch_free_string(&((*spec)->derefattr));
+        slapi_ch_array_free((*spec)->attrs);
+        slapi_ch_free((void **)spec);
+    }
+}
+
+typedef struct _DerefSpecList {
+    DerefSpec **list;
+    int count;
+} DerefSpecList;
+
+static DerefSpecList*
+new_DerefSpecList(void) {
+    DerefSpecList *speclist = (DerefSpecList *)slapi_ch_calloc(1, sizeof(DerefSpecList));
+
+    return speclist;
+}
+
+static void
+delete_DerefSpecList(DerefSpecList **speclist)
+{
+    if (speclist && *speclist) {
+        int ii;
+        for (ii = 0; ii < (*speclist)->count; ++ii) {
+            delete_DerefSpec(&((*speclist)->list[ii]));
+        }
+        slapi_ch_free((void **)&((*speclist)->list));
+        slapi_ch_free((void **)speclist);
+    }
+}
+
+static int deref_register_operation_extension(void);
+static int deref_extension_type;
+static int deref_extension_handle;
+
+static const DerefSpecList *
+deref_get_operation_extension(Slapi_PBlock *pb)
+{
+    Slapi_Operation *op;
+
+    slapi_pblock_get(pb, SLAPI_OPERATION, &op);
+    return (const DerefSpecList *)slapi_get_object_extension(deref_extension_type,
+                                                             op, deref_extension_handle);
+}
+
+static void
+deref_set_operation_extension(Slapi_PBlock *pb, DerefSpecList *speclist)
+{
+    Slapi_Operation *op;
+
+    slapi_pblock_get(pb, SLAPI_OPERATION, &op);
+    slapi_set_object_extension(deref_extension_type, op,
+                               deref_extension_handle, (void *)speclist);
+}
+
+/*
+ * Plugin identity functions
+ */
+void
+deref_set_plugin_id(void *pluginID)
+{
+    _PluginID = pluginID;
+}
+
+void *
+deref_get_plugin_id()
+{
+    return _PluginID;
+}
+
+void
+deref_set_plugin_dn(char *pluginDN)
+{
+    _PluginDN = pluginDN;
+}
+
+char *
+deref_get_plugin_dn()
+{
+    return _PluginDN;
+}
+
+/*
+ * Plug-in initialization functions
+ */
+int
+deref_init(Slapi_PBlock *pb)
+{
+    int status = 0;
+    char *plugin_identity = NULL;
+
+    slapi_log_error(SLAPI_LOG_TRACE, DEREF_PLUGIN_SUBSYSTEM,
+                    "--> deref_init\n");
+
+    /* Store the plugin identity for later use.
+     * Used for internal operations. */
+    slapi_pblock_get(pb, SLAPI_PLUGIN_IDENTITY, &plugin_identity);
+    PR_ASSERT(plugin_identity);
+    deref_set_plugin_id(plugin_identity);
+
+    /* Register callbacks */
+    if (slapi_pblock_set(pb, SLAPI_PLUGIN_VERSION,
+                         SLAPI_PLUGIN_VERSION_01) != 0 ||
+        slapi_pblock_set(pb, SLAPI_PLUGIN_START_FN,
+                         (void *) deref_start) != 0 ||
+        slapi_pblock_set(pb, SLAPI_PLUGIN_CLOSE_FN,
+                         (void *) deref_close) != 0 ||
+        slapi_pblock_set(pb, SLAPI_PLUGIN_DESCRIPTION,
+                         (void *) &pdesc) != 0 ||
+        slapi_pblock_set(pb, SLAPI_PLUGIN_PRE_SEARCH_FN,
+                         (void *) deref_pre_search) != 0 ||
+        slapi_pblock_set(pb, SLAPI_PLUGIN_PRE_ENTRY_FN,
+                         (void *) deref_pre_entry) != 0 ||
+        deref_register_operation_extension()
+        ) {
+        slapi_log_error(SLAPI_LOG_FATAL, DEREF_PLUGIN_SUBSYSTEM,
+                        "deref_init: failed to register plugin\n");
+        status = -1;
+    }
+
+    if (status == 0) {
+        slapi_register_supported_control(LDAP_CONTROL_X_DEREF, SLAPI_OPERATION_SEARCH);
+    }
+
+    slapi_log_error(SLAPI_LOG_TRACE, DEREF_PLUGIN_SUBSYSTEM,
+                    "<-- deref_init\n");
+    return status;
+}
+
+
+/*
+ * deref_start()
+ *
+ * Creates config lock and loads config cache.
+ */
+static int
+deref_start(Slapi_PBlock * pb)
+{
+    slapi_log_error(SLAPI_LOG_TRACE, DEREF_PLUGIN_SUBSYSTEM,
+                    "--> deref_start\n");
+
+    /* Check if we're already started */
+    if (g_plugin_started) {
+        goto done;
+    }
+
+    g_plugin_started = 1;
+    slapi_log_error(SLAPI_LOG_PLUGIN, DEREF_PLUGIN_SUBSYSTEM,
+                    "linked attributes plug-in: ready for service\n");
+    slapi_log_error(SLAPI_LOG_TRACE, DEREF_PLUGIN_SUBSYSTEM,
+                    "<-- deref_start\n");
+
+done:
+    return 0;
+}
+
+/*
+ * deref_close()
+ *
+ * Cleans up the config cache.
+ */
+static int
+deref_close(Slapi_PBlock * pb)
+{
+    slapi_log_error(SLAPI_LOG_TRACE, DEREF_PLUGIN_SUBSYSTEM,
+                    "--> deref_close\n");
+
+    slapi_log_error(SLAPI_LOG_TRACE, DEREF_PLUGIN_SUBSYSTEM,
+                    "<-- deref_close\n");
+
+    return 0;
+}
+
+static int
+deref_attr_in_spec_list(DerefSpecList *speclist, const char *derefattr)
+{
+    int ii;
+    int ret = 0;
+
+    PR_ASSERT(speclist && derefattr);
+
+    for (ii = 0; !ret && (ii < speclist->count); ++ii) {
+        if (slapi_attr_types_equivalent(derefattr, speclist->list[ii]->derefattr)) {
+            ret = 1; /* match */
+        }
+    }
+
+    return ret;
+}
+
+/* grows spec list, consumes spec */
+static void
+deref_add_spec_to_list(DerefSpecList *speclist, DerefSpec *spec)
+{
+    PR_ASSERT(speclist && spec);
+
+    speclist->count++;
+    speclist->list = (DerefSpec **)slapi_ch_realloc((char *)speclist->list,
+                                                    speclist->count * sizeof(DerefSpec *));
+    speclist->list[speclist->count-1] = spec; /* consumed */
+}
+
+static const DerefSpec *
+deref_get_next_spec(const DerefSpecList *speclist, int *ii)
+{
+    const DerefSpec *spec = NULL;
+
+    if (*ii < speclist->count) {
+        spec = speclist->list[*ii];
+        (*ii)++;
+    }
+
+    return spec;
+}
+
+static const DerefSpec *
+deref_get_first_spec(const DerefSpecList *speclist, int *ii)
+{
+    *ii = 0;
+    return deref_get_next_spec(speclist, ii);
+}
+
+static int
+deref_check_for_dn_syntax(const char *derefattr)
+{
+    int ret = 0;
+    Slapi_Attr *attr = slapi_attr_new();
+
+    if (attr) {
+        char *oid = NULL;
+
+        slapi_attr_init(attr, derefattr);
+        slapi_attr_get_syntax_oid_copy(attr, &oid);
+        ret = oid && !strcmp(oid, DN_SYNTAX_OID);
+        slapi_ch_free_string(&oid);
+        slapi_attr_free(&attr);
+    }
+
+    return ret;
+}
+
+static void
+deref_add_spec(DerefSpecList *speclist, char **derefattr, char ***attrs, int critical, int *ldapcode, const char **ldaperrtext)
+{
+    PR_ASSERT(speclist && derefattr && attrs && ldapcode && ldaperrtext);
+
+    if (!deref_check_for_dn_syntax(*derefattr)) { /* derefattr must have DN syntax */
+        if (critical) {
+            /* not DN syntax */
+            *ldapcode = LDAP_PROTOCOL_ERROR;
+            *ldaperrtext = "A dereference attribute must have DN syntax";
+        }
+    } else if (deref_attr_in_spec_list(speclist, *derefattr)) {
+        /* duplicate */
+        *ldapcode = LDAP_PROTOCOL_ERROR;
+        *ldaperrtext = "A dereference attribute was specified more than once in a dereference specification";
+    } else {
+        DerefSpec *spec = new_DerefSpec(*derefattr, *attrs);
+        *derefattr = NULL; /* consumed */
+        *attrs = NULL; /* consumed */
+        deref_add_spec_to_list(speclist, spec); /* consumes spec */
+    }
+
+    return;
+}
+
+/*
+         controlValue ::= SEQUENCE OF derefSpec DerefSpec
+
+         DerefSpec ::= SEQUENCE {
+             derefAttr       attributeDescription,    ; with DN syntax
+             attributes      AttributeList }
+
+         AttributeList ::= SEQUENCE OF attr AttributeDescription
+
+   Each derefSpec.derefAttr MUST be unique within controlValue.
+ */
+static void
+deref_parse_ctrl_value(DerefSpecList *speclist, const struct berval *ctrlbv, int critical, int *ldapcode, const char **ldaperrtext)
+{
+    BerElement *ber = NULL;
+    ber_tag_t tag;
+    ber_len_t len = -1;
+    char *last;
+
+    PR_ASSERT(ctrlbv && ctrlbv->bv_val && ctrlbv->bv_len && ldapcode && ldaperrtext);
+
+    ber = ber_init(ctrlbv);
+	for (tag = ber_first_element(ber, &len, &last);
+         (tag != LBER_ERROR) && (tag != LBER_END_OF_SEQORSET);
+         tag = ber_next_element(ber, &len, last)) {
+        char *derefattr = NULL;
+        char **attrs = NULL;
+		len = -1; /* reset */
+        if ((LBER_ERROR == ber_scanf(ber, "{a{v}}", &derefattr, &attrs)) ||
+            !derefattr || !attrs || !attrs[0]){
+            *ldapcode = LDAP_PROTOCOL_ERROR;
+            if (!derefattr) {
+                *ldaperrtext = "Missing dereference attribute name";
+            } else {
+                *ldaperrtext = "Missing list of attributes to dereference";
+            }
+        } else {
+            /* will consume derefattr and attrs and set them to NULL if successful */
+            deref_add_spec(speclist, &derefattr, &attrs, critical, ldapcode, ldaperrtext);
+        }
+        if (derefattr) { /* not consumed - error */
+            slapi_ch_free_string(&derefattr);
+        }
+        if (attrs) { /* not consumed - error */
+            slapi_ch_array_free(attrs);
+        }
+    }
+    ber_free(ber, 1);
+}
+
+static int
+deref_incompatible_ctrl(const char *oid)
+{
+    return 0; /* no known incompatible ctrls yet */
+}
+
+/*
+ * Operation callback functions
+ */
+
+/*
+ * deref_pre_search()
+ *
+ * see if the dereference control has been specified
+ * if so, parse it, and check to make sure it meets the
+ * protocol specification (no duplicate attributes, etc.)
+ */
+static int
+deref_pre_search(Slapi_PBlock *pb)
+{
+    int ldapcode = LDAP_SUCCESS;
+    const LDAPControl **reqctrls = NULL;
+    const LDAPControl *derefctrl = NULL;
+    const char *ldaperrtext;
+    const char *incompatible = NULL;
+    DerefSpecList *speclist = NULL;
+    int ii;
+
+    slapi_log_error(SLAPI_LOG_TRACE, DEREF_PLUGIN_SUBSYSTEM,
+                    "--> deref_pre_search\n");
+
+    /* see if the deref request control is in the list of 
+       controls - if so, parse and validate it */
+    slapi_pblock_get(pb, SLAPI_REQCONTROLS, &reqctrls);
+    for (ii = 0; (ldapcode == LDAP_SUCCESS) && reqctrls && reqctrls[ii]; ++ii) {
+        const LDAPControl *ctrl = reqctrls[ii];
+        if (!strcmp(ctrl->ldctl_oid, LDAP_CONTROL_X_DEREF)) {
+            if (derefctrl) { /* already specified */
+                slapi_log_error(SLAPI_LOG_FATAL, DEREF_PLUGIN_SUBSYSTEM,
+                                "The dereference control was specified more than once - it must be specified only once in the search request\n");
+                ldapcode = LDAP_PROTOCOL_ERROR;
+                ldaperrtext = "The dereference control cannot be specified more than once";
+                derefctrl = NULL;
+            } else if (!ctrl->ldctl_value.bv_len) {
+                slapi_log_error(SLAPI_LOG_FATAL, DEREF_PLUGIN_SUBSYSTEM,
+                                "No control value specified for dereference control\n");
+                ldapcode = LDAP_PROTOCOL_ERROR;
+                ldaperrtext = "The dereference control must have a value";
+            } else if (!ctrl->ldctl_value.bv_val) {
+                slapi_log_error(SLAPI_LOG_FATAL, DEREF_PLUGIN_SUBSYSTEM,
+                                "No control value specified for dereference control\n");
+                ldapcode = LDAP_PROTOCOL_ERROR;
+                ldaperrtext = "The dereference control must have a value";
+            } else if (!ctrl->ldctl_value.bv_val[0] || !ctrl->ldctl_value.bv_len) {
+                slapi_log_error(SLAPI_LOG_FATAL, DEREF_PLUGIN_SUBSYSTEM,
+                                "Empty control value specified for dereference control\n");
+                ldapcode = LDAP_PROTOCOL_ERROR;
+                ldaperrtext = "The dereference control must have a non-empty value";
+            } else {
+                derefctrl = ctrl;
+            }
+        } else if (deref_incompatible_ctrl(ctrl->ldctl_oid)) {
+            incompatible = ctrl->ldctl_oid;
+        }
+    }
+
+    if (derefctrl && incompatible) {
+        slapi_log_error(SLAPI_LOG_FATAL, DEREF_PLUGIN_SUBSYSTEM,
+                        "Cannot use the dereference control and control [%s] for the same search operation\n",
+                        incompatible);
+        /* not sure if this is a hard failure - the current spec says:
+           The semantics of the criticality field are specified in [RFC4511].
+           In detail, the criticality of the control determines whether the
+           control will or will not be used, and if it will not be used, whether
+           the operation will continue without returning the control in the
+           response, or fail, returning unavailableCriticalExtension.  If the
+           control is appropriate for an operation and, for any reason, it
+           cannot be applied in its entirety to a single SearchResultEntry
+           response, it MUST NOT be applied to that specific SearchResultEntry
+           response, without affecting its application to any subsequent
+           SearchResultEntry response.
+        */
+        /* so for now, just return LDAP_SUCCESS and don't do anything else */
+        derefctrl = NULL;
+    }
+
+    /* we have something now - see if it is a valid control */
+    if (derefctrl) {
+        speclist = new_DerefSpecList();
+        deref_parse_ctrl_value(speclist, &derefctrl->ldctl_value, derefctrl->ldctl_iscritical,
+                               &ldapcode, &ldaperrtext);
+    }
+
+    if (ldapcode != LDAP_SUCCESS) {
+        slapi_pblock_set(pb, SLAPI_PLUGIN_OPRETURN, &ldapcode);
+        slapi_send_ldap_result(pb, ldapcode, NULL, (char *)ldaperrtext, 0, NULL);
+        delete_DerefSpecList(&speclist);
+    } else {
+        /* save spec list away for the pre_entry callback */
+        deref_set_operation_extension(pb, speclist);
+    }
+
+    slapi_log_error(SLAPI_LOG_TRACE, DEREF_PLUGIN_SUBSYSTEM,
+                    "<-- deref_pre_op\n");
+
+    return ldapcode;
+}
+
+/*
+  See if the client has the requested rights over the entry and the specified
+  attributes.  Each attribute in attrs will be tested.  The retattrs array will
+  hold the attributes that could be read.  If NULL, this means the entry is
+  not allowed, or none of the requested attributes are allowed.  If non-NULL, this
+  array can be passed to a subsequent search operation.
+*/
+static int
+deref_check_access(Slapi_PBlock *pb, const Slapi_Entry *ent, const char *entdn,
+                   const char **attrs, char ***retattrs, int rights)
+{
+    Slapi_Entry *etest = NULL;
+    const char *attrname;
+
+    /* if there is no entry, create a dummy entry - this can save a search
+       on an entry we should not be allowed to search */
+    if (!ent) {
+        etest = slapi_entry_alloc();
+        slapi_sdn_set_dn_byref(slapi_entry_get_sdn(etest), entdn);
+    } else {
+        etest = (Slapi_Entry *)ent;
+    }
+
+    *retattrs = NULL;
+    for (attrname = *attrs; attrname; attrname = *(++attrs)) {
+        /* first, check access control - see if client can read the requested attribute */
+        int ret = slapi_access_allowed(pb, etest, (char *)attrname, NULL, rights);
+        if (ret != LDAP_SUCCESS) {
+            slapi_log_error(SLAPI_LOG_PLUGIN, DEREF_PLUGIN_SUBSYSTEM,
+                            "The client does not have permission to read attribute %s in entry %s\n",
+                            attrname, slapi_entry_get_dn_const(etest));
+        } else {
+            slapi_ch_array_add(retattrs, (char *)attrname); /* retattrs and attrs share pointer to attrname */
+        }
+    }
+
+    if (ent != etest) {
+        slapi_entry_free(etest);
+    }
+
+    /* see if we had at least one attribute that could be accessed */
+    return *retattrs == NULL ? LDAP_INSUFFICIENT_ACCESS : LDAP_SUCCESS;
+}
+
+/*
+  must check access before calling this function
+*/
+static int
+deref_get_values(const Slapi_Entry *ent, const char *attrname,
+                 Slapi_ValueSet** results, int *type_name_disposition,
+                 char** actual_type_name, int flags, int *buffer_flags)
+{
+    int ret = slapi_vattr_values_get((Slapi_Entry *)ent, (char *)attrname, results, type_name_disposition,
+                                     actual_type_name, flags, buffer_flags);
+
+    return ret;
+}
+
+static void
+deref_values_free(Slapi_ValueSet** results, char** actual_type_name, int buffer_flags)
+{
+    slapi_vattr_values_free(results, actual_type_name, buffer_flags);
+}
+
+static void
+deref_do_deref_attr(Slapi_PBlock *pb, BerElement *ctrlber, const char *derefdn, const char **attrs)
+{
+    char **retattrs = NULL;
+    Slapi_PBlock *derefpb = NULL;
+    Slapi_Entry **entries = NULL;
+    int rc;
+
+    if (deref_check_access(pb, NULL, derefdn, attrs, &retattrs,
+                           (SLAPI_ACL_SEARCH|SLAPI_ACL_READ))) {
+        slapi_log_error(SLAPI_LOG_PLUGIN, DEREF_PLUGIN_SUBSYSTEM,
+                        "The client does not have permission to read the requested "
+                        "attributes in entry %s\n", derefdn);
+        return;
+    }
+
+    derefpb = slapi_pblock_new();
+    slapi_search_internal_set_pb(derefpb, derefdn, LDAP_SCOPE_BASE,
+                                 "(objectclass=*)", retattrs, 0,
+                                 NULL, NULL, deref_get_plugin_id(), 0);
+
+    slapi_search_internal_pb(derefpb);
+    slapi_pblock_get(derefpb, SLAPI_PLUGIN_INTOP_RESULT, &rc);
+    if (LDAP_SUCCESS == rc) {
+        slapi_pblock_get(derefpb, SLAPI_PLUGIN_INTOP_SEARCH_ENTRIES, &entries);
+        if (entries) {
+            if (entries[1]) {
+                /* too many entries */
+                slapi_log_error(SLAPI_LOG_PLUGIN, DEREF_PLUGIN_SUBSYSTEM,
+                                "More than one entry matching DN [%s]\n",
+                                derefdn);
+            } else {
+                int ii;
+                int needattrvals = 1; /* need attrvals sequence? */
+                for (ii = 0; retattrs[ii]; ++ii) {
+                    Slapi_Value *sv;
+                    int idx = 0;
+                    Slapi_ValueSet* results = NULL;
+                    int type_name_disposition = 0;
+                    char* actual_type_name = NULL;
+                    int flags = 0;
+                    int buffer_flags = 0;
+                    int needpartialattr = 1; /* need PartialAttribute sequence? */
+                    int needvalsset = 1;
+
+                    deref_get_values(entries[0], retattrs[ii], &results, &type_name_disposition,
+                                     &actual_type_name, flags, &buffer_flags);
+
+                    if (results) {
+                        idx = slapi_valueset_first_value(results, &sv);
+                    }
+                    for (; results && sv; idx = slapi_valueset_next_value(results, idx, &sv)) {
+                        const struct berval *bv = slapi_value_get_berval(sv);
+                        if (needattrvals) {
+                            /* we have at least one attribute with values in
+                               DerefRes.attrVals */
+                            /* attrVals is OPTIONAL - only added if there are
+                               any values to send */
+                            ber_printf(ctrlber, "t{", (LBER_CLASS_CONTEXT|LBER_CONSTRUCTED));
+                            needattrvals = 0;
+                        }
+                        if (needpartialattr) {
+                            /* This attribute in attrVals has values */
+                            ber_printf(ctrlber, "{s", retattrs[ii]);
+                            needpartialattr = 0;
+                        }
+                        if (needvalsset) {
+                            /* begin the vals SET of values for this attribute */
+                            ber_printf(ctrlber, "[");
+                            needvalsset = 0;
+                        }
+                        ber_printf(ctrlber, "O", bv);
+                    } /* for each value in retattrs[ii] */
+                    deref_values_free(&results, &actual_type_name, buffer_flags);
+                    if (needvalsset == 0) {
+                        ber_printf(ctrlber, "]");
+                    }
+                    if (needpartialattr == 0) {
+                        ber_printf(ctrlber, "}");
+                    }
+                } /* for each attr in retattrs */
+                if (needattrvals == 0) {
+                    ber_printf(ctrlber, "}");
+                }
+            }
+        } else { /* nothing */
+            slapi_log_error(SLAPI_LOG_PLUGIN, DEREF_PLUGIN_SUBSYSTEM,
+                            "No entries matching [%s]\n", derefdn);
+        }
+    } else {
+        /* handle error */
+        slapi_log_error(SLAPI_LOG_PLUGIN, DEREF_PLUGIN_SUBSYSTEM,
+                        "Could not read entry with DN [%s]: error %d:%s\n",
+                        derefdn, rc, ldap_err2string(rc));
+    }
+    slapi_free_search_results_internal(derefpb);
+    slapi_pblock_destroy(derefpb);
+    slapi_ch_free((void **)&retattrs); /* retattrs does not own the strings */
+
+    return;
+}
+
+static int
+deref_pre_entry(Slapi_PBlock *pb)
+{
+    int ii = 0;
+    const DerefSpec *spec;
+    const Slapi_Entry *ent = NULL;
+    const DerefSpecList *speclist = deref_get_operation_extension(pb);
+    BerElement *ctrlber = NULL;
+    LDAPControl *ctrl = NULL;
+    const LDAPControl **searchctrls = NULL;
+    LDAPControl **newsearchctrls = NULL;
+
+    if (!speclist) {
+        return 0; /* nothing to do */
+    }
+
+    ctrlber = ber_alloc();
+    ber_printf(ctrlber, "{"); /* begin control value */
+
+    slapi_pblock_get(pb, SLAPI_SEARCH_ENTRY_ORIG, &ent);
+    for (spec = deref_get_first_spec(speclist, &ii); spec;
+         spec = deref_get_next_spec(speclist, &ii)) {
+        Slapi_Value *sv;
+        int idx = 0;
+        Slapi_ValueSet* results = NULL;
+        int type_name_disposition = 0;
+        char* actual_type_name = NULL;
+        int flags = 0;
+        int buffer_flags = 0;
+        const char *attrs[2];
+        char **retattrs = NULL;
+
+        attrs[0] = spec->derefattr;
+        attrs[1] = NULL;
+
+        if (deref_check_access(pb, ent, NULL, attrs, &retattrs,
+                               (SLAPI_ACL_SEARCH|SLAPI_ACL_READ))) {
+            slapi_log_error(SLAPI_LOG_PLUGIN, DEREF_PLUGIN_SUBSYSTEM,
+                            "The client does not have permission to read attribute %s in entry %s\n",
+                            spec->derefattr, slapi_entry_get_dn_const(ent));
+            continue;
+        }
+
+        slapi_ch_free((void **)&retattrs); /* retattrs does not own strings */
+        deref_get_values(ent, spec->derefattr, &results, &type_name_disposition,
+                         &actual_type_name, flags, &buffer_flags);
+
+        /* spec->derefattr is DN valued attr - results will be a list of DNs */
+        if (results) {
+            idx = slapi_valueset_first_value(results, &sv);
+        }
+        for (; results && sv; idx = slapi_valueset_next_value(results, idx, &sv)) {
+            const char *derefdn = slapi_value_get_string(sv);
+
+            ber_printf(ctrlber, "{ss", spec->derefattr, derefdn); /* begin DerefRes + derefAttr + derefVal */
+            deref_do_deref_attr(pb, ctrlber, derefdn, (const char **)spec->attrs);
+            ber_printf(ctrlber, "}"); /* end DerefRes */
+        }
+        deref_values_free(&results, &actual_type_name, buffer_flags);
+    }
+
+    ber_printf(ctrlber, "}"); /* end control val */
+
+    slapi_build_control(LDAP_CONTROL_X_DEREF, ctrlber, 0, &ctrl);
+
+    ber_free(ctrlber, 1);
+
+    /* get the list of controls */
+	slapi_pblock_get(pb, SLAPI_SEARCH_CTRLS, &searchctrls);
+
+    /* dup them */
+    slapi_add_controls(&newsearchctrls, (LDAPControl **)searchctrls, 1);
+
+    /* add our control */
+    slapi_add_control_ext(&newsearchctrls, ctrl, 0);
+    ctrl = NULL; /* newsearchctrls owns it now */
+
+    /* set the controls in the pblock */
+    slapi_pblock_set(pb, SLAPI_SEARCH_CTRLS, newsearchctrls);
+
+    return 0;
+}
+
+/* consumer operation extension constructor */
+static void *
+deref_operation_extension_ctor(void *object, void *parent)
+{
+    /* we only set the extension value explicitly if the
+       client requested the control - see deref_pre_search */
+    return NULL; /* we don't set anything in the ctor */
+}
+
+/* consumer operation extension destructor */
+static void
+deref_operation_extension_dtor(void *ext, void *object, void *parent)
+{
+    DerefSpecList *speclist = (DerefSpecList *)ext;
+    delete_DerefSpecList(&speclist);
+}
+
+static int
+deref_register_operation_extension(void)
+{
+	return slapi_register_object_extension(DEREF_PLUGIN_SUBSYSTEM,
+                                           SLAPI_EXT_OPERATION, 
+                                           deref_operation_extension_ctor,
+                                           deref_operation_extension_dtor,
+                                           &deref_extension_type,
+                                           &deref_extension_handle);
+}
diff --git a/ldap/servers/plugins/deref/deref.h b/ldap/servers/plugins/deref/deref.h
new file mode 100644
index 00000000..e780c9cd
--- /dev/null
+++ b/ldap/servers/plugins/deref/deref.h
@@ -0,0 +1,58 @@
+/** BEGIN COPYRIGHT BLOCK
+ * This Program is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation; version 2 of the License.
+ *
+ * This Program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this Program; if not, write to the Free Software Foundation, Inc., 59 Temple
+ * Place, Suite 330, Boston, MA 02111-1307 USA.
+ *
+ * In addition, as a special exception, Red Hat, Inc. gives You the additional
+ * right to link the code of this Program with code not covered under the GNU
+ * General Public License ("Non-GPL Code") and to distribute linked combinations
+ * including the two, subject to the limitations in this paragraph. Non-GPL Code
+ * permitted under this exception must only link to the code of this Program
+ * through those well defined interfaces identified in the file named EXCEPTION
+ * found in the source code files (the "Approved Interfaces"). The files of
+ * Non-GPL Code may instantiate templates or use macros or inline functions from
+ * the Approved Interfaces without causing the resulting work to be covered by
+ * the GNU General Public License. Only Red Hat, Inc. may make changes or
+ * additions to the list of Approved Interfaces. You must obey the GNU General
+ * Public License in all respects for all of the Program code and other code used
+ * in conjunction with the Program except the Non-GPL Code covered by this
+ * exception. If you modify this file, you may extend this exception to your
+ * version of the file, but you are not obligated to do so. If you do not wish to
+ * provide this exception without modification, you must delete this exception
+ * statement from your version and license this file solely under the GPL without
+ * exception.
+ *
+ *
+ * Copyright (C) 2009 Red Hat, Inc.
+ * All rights reserved.
+ * END COPYRIGHT BLOCK **/
+
+#ifdef HAVE_CONFIG_H
+#  include <config.h>
+#endif
+
+/*
+ * Dereference plug-in header file
+ */
+#include "slapi-plugin.h"
+
+/*
+ * Plug-in defines
+ */
+#define DEREF_PLUGIN_SUBSYSTEM  "deref-plugin"
+#define DEREF_FEATURE_DESC      "Dereference"
+#define DEREF_PLUGIN_DESC       "Dereference plugin"
+#define DEREF_INT_PREOP_DESC    "Dereference internal preop plugin"
+#define DEREF_PREOP_DESC        "Dereference preop plugin"
+
+#ifndef LDAP_CONTROL_X_DEREF
+#define	LDAP_CONTROL_X_DEREF			"1.3.6.1.4.1.4203.666.5.16"
+#endif
diff --git a/ldap/servers/slapd/pblock.c b/ldap/servers/slapd/pblock.c
index e5751a92..419ca959 100644
--- a/ldap/servers/slapd/pblock.c
+++ b/ldap/servers/slapd/pblock.c
@@ -1634,6 +1634,10 @@ slapi_pblock_get( Slapi_PBlock *pblock, int arg, void *value )
 		(*(char **)value) = pblock->pb_urp_tombstone_uniqueid;
 		break;
 		
+	case SLAPI_SEARCH_CTRLS:
+		(*(LDAPControl ***)value) = pblock->pb_search_ctrls;
+		break;
+		
 	default:
 		LDAPDebug( LDAP_DEBUG_ANY,
 		    "Unknown parameter block argument %d\n", arg, 0, 0 );
@@ -2908,6 +2912,10 @@ slapi_pblock_set( Slapi_PBlock *pblock, int arg, void *value )
 		pblock->pb_ldif_encrypt = *((int *)value);
 		break;
 
+	case SLAPI_SEARCH_CTRLS:
+		pblock->pb_search_ctrls = (LDAPControl **) value;
+		break;
+
 	default:
 		LDAPDebug( LDAP_DEBUG_ANY,
 		    "Unknown parameter block argument %d\n", arg, 0, 0 );
diff --git a/ldap/servers/slapd/result.c b/ldap/servers/slapd/result.c
index cd02f01f..2884d11b 100644
--- a/ldap/servers/slapd/result.c
+++ b/ldap/servers/slapd/result.c
@@ -1181,7 +1181,7 @@ send_ldap_search_entry_ext(
 {
 	Connection	*conn = pb->pb_conn;
 	Operation	*op = pb->pb_op;
-	BerElement	*ber;
+	BerElement	*ber = NULL;
 	int		i, rc = 0, logit = 0;
 	int		alluserattrs, noattrs, some_named_attrs;
 	int *dontsendattr= NULL;
@@ -1189,12 +1189,35 @@ send_ldap_search_entry_ext(
 	int real_attrs_only = 0;
 	LDAPControl		**ctrlp = 0;
 	Slapi_Entry *gerentry = NULL;
+	Slapi_Entry *ecopy = NULL;
+	LDAPControl	**searchctrlp = NULL;
+	
 
 	slapi_pblock_get (pb, SLAPI_OPERATION, &operation);
 
 	LDAPDebug( LDAP_DEBUG_TRACE, "=> send_ldap_search_entry (%s)\n",
 	    e?slapi_entry_get_dn_const(e):"null", 0, 0 );
 
+	/* set current entry */
+	slapi_pblock_set(pb, SLAPI_SEARCH_ENTRY_ORIG, e);
+	/* set controls */
+	slapi_pblock_set(pb, SLAPI_SEARCH_CTRLS, ectrls);
+
+	/* call pre entry fn */
+	rc = plugin_call_plugins(pb, SLAPI_PLUGIN_PRE_ENTRY_FN);
+	if (rc) {
+		LDAPDebug( LDAP_DEBUG_ANY,
+				   "error returned by pre entry plugins for entry %s\n",
+				   e?slapi_entry_get_dn_const(e):"null", 0, 0 );
+		goto cleanup;
+	}
+
+	slapi_pblock_get(pb, SLAPI_SEARCH_ENTRY_COPY, &ecopy);
+	if (ecopy) {
+		e = ecopy; /* send back the altered entry */
+	}
+	slapi_pblock_get(pb, SLAPI_SEARCH_CTRLS, &searchctrlp);
+
 	if ( conn == NULL && e ) {
 		if ( op->o_search_entry_handler != NULL ) {
 			if (( rc = (*op->o_search_entry_handler)(
@@ -1202,10 +1225,11 @@ send_ldap_search_entry_ext(
 				logit = 1;
 				goto log_and_return;
 			} else {
-				return rc;
+				goto cleanup;
 			}
 		}
-		return 0;
+		rc = 0;
+		goto cleanup;
 	}
 
 #if !defined(DISABLE_ACL_CHECK)
@@ -1213,19 +1237,22 @@ send_ldap_search_entry_ext(
 				    SLAPI_ACL_READ, ACLPLUGIN_ACCESS_READ_ON_ENTRY, NULL ) != LDAP_SUCCESS ) {
 		LDAPDebug( LDAP_DEBUG_ACL, "acl: access to entry not allowed\n",
 		    0, 0, 0 );
-		return( 1 );
+		rc = 1;
+		goto cleanup;
 	}
 #endif
 
 	if (NULL == e) {
-		return 1;	/* everything is ok - don't send the result */
+		rc = 1;	/* everything is ok - don't send the result */
+		goto cleanup;
 	}
 
 	if ( (ber = der_alloc()) == NULL ) {
 		LDAPDebug( LDAP_DEBUG_ANY, "ber_alloc failed\n", 0, 0, 0 );
 		send_ldap_result( pb, LDAP_OPERATIONS_ERROR, NULL,
 		    "ber_alloc", 0, NULL );
-		return( -1 );
+		rc = -1;
+		goto cleanup;
 	}
 
 	rc = ber_printf( ber, "{it{s{", op->o_msgid,
@@ -1233,10 +1260,9 @@ send_ldap_search_entry_ext(
 
 	if ( rc == -1 ) {
 		LDAPDebug( LDAP_DEBUG_ANY, "ber_printf failed\n", 0, 0, 0 );
-		ber_free( ber, 1 );
 		send_ldap_result( pb, LDAP_OPERATIONS_ERROR, NULL,
 		    "ber_printf dn", 0, NULL );
-		return( -1 );
+		goto cleanup;
 	}
 
 	/*
@@ -1292,11 +1318,10 @@ send_ldap_search_entry_ext(
 		else
 		{
 			/* we cannot service a request for virtual only and real only */
-			ber_free( ber, 1 );
-    			slapi_ch_free( (void **) &dontsendattr );
 			send_ldap_result( pb, LDAP_OPERATIONS_ERROR, NULL,
 				"Both real and virtual attributes only controls", 0, NULL );
-			return( -1 );
+			rc = -1;
+			goto cleanup;
 		}
 	}
 
@@ -1335,23 +1360,20 @@ send_ldap_search_entry_ext(
 		}
 	}
 
-    slapi_ch_free( (void **) &dontsendattr ); /* I know it looks like we could free this when it wasn't allocated, the function ignores null pointers */
-
 	if (rc != 0) {
-		ber_free( ber, 1 );
-		goto exit;
+		goto cleanup;
 	}
 
 	rc = ber_printf( ber, "}}" );
 
 	if ( conn->c_ldapversion >= LDAP_VERSION3 ) {
-		if ( ectrls != NULL ) {
-			rc = write_controls( ber, ectrls );
+		if ( searchctrlp != NULL ) {
+			rc = write_controls( ber, searchctrlp );
 		}
 		/*
 		 * The get-effective-rights control is called within
 		 * the current function. Hence it can't be already in
-		 * ectrls
+		 * searchctrlp
 		 */
 		if ( operation->o_flags & OP_FLAG_GET_EFFECTIVE_RIGHTS ) {
 			LDAPControl *gerctrl[2];
@@ -1386,10 +1408,9 @@ send_ldap_search_entry_ext(
 
 	if ( rc == -1 ) {
 		LDAPDebug( LDAP_DEBUG_ANY, "ber_printf failed\n", 0, 0, 0 );
-		ber_free( ber, 1 );
 		send_ldap_result( pb, LDAP_OPERATIONS_ERROR, NULL,
 		    "ber_printf entry end", 0, NULL );
-		return( -1 );
+		goto cleanup;
 	}
 
 	if (send_result) {
@@ -1400,6 +1421,7 @@ send_ldap_search_entry_ext(
 	if ( (rc = flush_ber( pb, conn, op, ber, _LDAP_SEND_ENTRY )) == 0 ) {
 		logit = 1;
 	}
+	ber = NULL; /* flush_ber will always free the ber */
 
 log_and_return:
 	if ( logit && operation_is_flag_set(operation,
@@ -1438,13 +1460,20 @@ log_and_return:
 		log_result( pb, op, LDAP_SUCCESS, tag, nentries );
 	    }
 	}
-
-	if (gerentry)
-	{
-		slapi_entry_free(gerentry);
-	}
+cleanup:
+	slapi_entry_free(gerentry);
+	slapi_pblock_get(pb, SLAPI_SEARCH_ENTRY_COPY, &ecopy);
+	slapi_pblock_set(pb, SLAPI_SEARCH_ENTRY_COPY, NULL);
+	slapi_entry_free(ecopy);
+	slapi_pblock_get(pb, SLAPI_SEARCH_CTRLS, &searchctrlp);
+	slapi_pblock_set(pb, SLAPI_SEARCH_CTRLS, NULL);
+	if (searchctrlp != ectrls) {
+		ldap_controls_free(searchctrlp);
+	}
+	ber_free( ber, 1 );
+	slapi_ch_free( (void **) &dontsendattr );
 	LDAPDebug( LDAP_DEBUG_TRACE, "<= send_ldap_search_entry\n", 0, 0, 0 );
-exit:
+
 	return( rc );
 }
 
@@ -1473,9 +1502,6 @@ flush_ber(
 	case _LDAP_SEND_REFERRAL:
 		rc = plugin_call_plugins( pb, SLAPI_PLUGIN_PRE_REFERRAL_FN );
 		break;
-	case _LDAP_SEND_ENTRY:
-		rc = plugin_call_plugins( pb, SLAPI_PLUGIN_PRE_ENTRY_FN );
-		break;
 	}
 
 	if ( rc != 0 ) {
diff --git a/ldap/servers/slapd/slap.h b/ldap/servers/slapd/slap.h
index 6eecd013..af8603db 100644
--- a/ldap/servers/slapd/slap.h
+++ b/ldap/servers/slapd/slap.h
@@ -1491,6 +1491,8 @@ typedef struct slapi_pblock {
 							 */
 	int		pb_plugin_enabled; /* nsslapd-pluginEnabled: on|off */
 							   /* used in plugin init; pb_plugin is not ready, then */
+	LDAPControl	**pb_search_ctrls; /* for search operations, allows plugins to provide
+									  controls to pass for each entry or referral returned */
 } slapi_pblock;
 
 /* index if substrlens */
diff --git a/ldap/servers/slapd/slapi-plugin.h b/ldap/servers/slapd/slapi-plugin.h
index d5efe4d5..e59df68b 100644
--- a/ldap/servers/slapd/slapi-plugin.h
+++ b/ldap/servers/slapd/slapi-plugin.h
@@ -3295,6 +3295,19 @@ typedef struct slapi_plugindesc {
 /* Copies of entry before and after add, mod, mod[r]dn operations */
 #define	SLAPI_ENTRY_PRE_OP			52
 #define	SLAPI_ENTRY_POST_OP			53
+/* a PRE_ENTRY_FN may alter the entry to be returned to the client -
+   SLAPI_SEARCH_ORIG_ENTRY holds the original entry from
+   the database - this must not be changed
+   SLAPI_SEARCH_ENTRY_COPY holds a copy of the original entry that
+   has been modified by the plugin - this will be NULL by default -
+   if a plugin needs to modify the entry, it should first check to
+   see if there is already a SLAPI_SEARCH_ENTRY_COPY - if not, the
+   plugin must use slapi_entry_dup() or similar to make a copy, edit
+   the copy, then store it in SLAPI_SEARCH_ENTRY_COPY - the internal
+   server code will free SLAPI_SEARCH_ENTRY_COPY
+*/
+#define	SLAPI_SEARCH_ENTRY_ORIG		SLAPI_ENTRY_PRE_OP
+#define	SLAPI_SEARCH_ENTRY_COPY		SLAPI_ENTRY_POST_OP
 
 /* LDAPv3 controls to be sent with the operation result */
 #define SLAPI_RESCONTROLS			55
@@ -3466,6 +3479,10 @@ typedef struct slapi_plugindesc {
 #define	SLAPI_NENTRIES				195
 /* Any referrals encountered during the search */
 #define SLAPI_SEARCH_REFERRALS			196
+/* for search operations, allows plugins to provide
+   controls to pass for each entry or referral returned
+   corresponds to pb_search_ctrls */
+#define SLAPI_SEARCH_CTRLS			198
 
 #define SLAPI_RESULT_CODE			881
 #define SLAPI_RESULT_TEXT			882