#
# 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) 2001 Sun Microsystems, Inc. Used by permission.
# Copyright (C) 2005 Red Hat, Inc.
# All rights reserved.
# END COPYRIGHT BLOCK
#
Unique UID Checking Plugin
--------------------------

Terry Hayes, April 16, 1998


GOALS

The Unique UID Checking Plugin supports the management of user entries in the
directory by enforcing the constraints on the value of an attribute within a
portion of the directory.  This provides a central point for enforcing this
constraint, which allows changes from any source to be checked (DSGW, Kingpin,
LDAP utilities, or user application).

CONFIGURATION

The software operates as a preoperation plugin to the directory server.  An
entry must be added to the slapd.conf file for the server that declares the
plugin and provides arguments required for its operation.

The plugin is declared as follows (line split for clarity):

  plugin preoperation "uid uniqueness" /home/thayes/testdir/lib/uid-plugin.so
    uidunique_init <attribute_name> <subtree_dn> ... 

The first 5 values are the standard plugin declaration.  The uidunique_init
function registers preoperation callbacks for the add, modify and modRDN
directory operations.

The next argument ("attribute_name") specifies the name of the entry attribute
to check for uniqueness.  This attribute must be unique within each of the
subtrees listed in the remainder of the arguments.

For example:

  plugin preoperation "uid uniqueness" /home/thayes/testdir/lib/uid-plugin.so
    uidunique_init uid o=mcom.com

This line specifies "uid" as the unique attribute, and lists a single subtree
to be checked.  This line is typical of an initial installation (see below).

A more complex case:

  plugin preoperation "uid uniqueness" /home/thayes/testdir/lib/uid-plugin.so
    uidunique_init uid o=Coke o=Pepsi
  plugin preoperation "uid uniqueness" /home/thayes/testdir/lib/uid-plugin.so
    uidunique_init mail "o=Dr. Pepper"

This configuration specifies a total of three subtrees to check.  Two use the
(standard) "uid" attribute as a unique value.  The other specifies "mail"
as the unique attribute.

INSTALLATION

The standard installation of the directory server will configure this plugin
to check the "uid" attribute on the default suffix.

OPERATION

The plugin responds to the following LDAP operations:

  + add
  + modify
  + modRDN

For all operations, the plugin forces the LDAP operation to return
CONSTRAINT_VIOLATION if the operation would result in two entries with
the same unique attribute value.

For an "add" operation that includes the unique attribute, the plugin checks
that no other entry has the same value.

For a "modify" operation, the operation will fail if the new value of the
attribute exists in any entry OTHER than the target of the modify.  If the
value already exists, but is in the node being changed, the operation
succeeds.  For example, if a modify operation replaces a 'uid' attribute
with the same set of values, the plugin will find the "new" values already
exist.  However since it is in the entry being modified, the operation is
allowed to complete.

For modRDN, the same checking as for "modify" is performed.

ModRDN is coded to handle reparenting, but since the LDAP protocol to support
this operation is not present, it cannot be exercised and has not been
tested.