389-ds-base/lib/ldaputil/examples/README

# 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
#

This directory contains an example program to demonstrate
writing plugins using the "Certificate to LDAP Mapping" API.
Please read the "Managing Servers" manual to find out
about how certificate to ldap mapping can be configured using
the <ServerRoot>/userdb/certmap.conf file.  Also refer to the
"Certificate to LDAP Mapping API" documentation to find out
about the various API functions and how you can write your
plugin.

This example demonstrate use of most of the API functions.  It
defines a mapping function, a search function, and a verify
function.  Read the API doc to learn about these functions.
The init.c file also contains an init function which sets the
mapping, search and verify functions.

The Mapping Function 
-------------------- 

The mapping function extracts the attributes "CN", "E", "O" and
"C" from the certificate's subject DN using the function
ldapu_get_cert_ava_val.  If the attributes "C" doesn't exists
then it defaults to "US".  It then gets the value of a custom
certmap.conf property "defaultOU" using the function
ldapu_certmap_info_attrval.  This demonstrates how you can have
your own custom properties defined in the certmap.conf file.
The mapping function then returns an ldapdn of the form:
"cn=<name>, ou=<defaultOU>, o=<o>, c=<c>".

If the "E" attribute has a value, it returns a filter
"mail=<e>".  Finally, the mapping function frees the structures
returned by some of the API functions it called.


The Search Function
-------------------

The search function calls a dummy function to get the
certificate's serial number.  It then does a subtree search in
the entire directory for the filter 
"certSerialNumber=<serial No.>".  If this fails, it calls the
default search function.  This demonstrates how you can use the
default functions in your custom functions.

The Verify Function
-------------------

The verify function returns LDAPU_SUCCESS if only one entry was
returned by the search function.  Otherwise, it returns
LDAPU_CERT_VERIFY_FUNCTION_FAILED.


Error Reporting
---------------

To report errors/warning, there is a function defined called
plugin_ereport.  This function demonstrates how to get the
subject DN and the issuer DN from the certificate.

Build Procedure
---------------
On UNIX: Edit the Makefile, and set the variables ARCH & SROOT
according to the comments in the Makefile.  Download LDAP C SDK
from the mozilla.org site and make the ldap include
files available in <SROOT>/include.  Copy the
../include/certmap.h file to the <SROOT>/include directory.
Use 'gmake' to build the plugin.  A shared library plugin.so
(plugin.sl on HP) will be created in the current directory.

On NT:  Execute the following command:
NMAKE /f "Certmap.mak" CFG="Certmap - Win32 Debug"
Certmap.dll will be created in the Debug subdirectory.

Certmap.conf Configuration
--------------------------
Save a copy of certmap.conf file.
Change the certmap.conf file as follows:

certmap default default
default:defaultOU   marketing
default:library	    <path to the shared library>
default:InitFn	    plugin_init_fn


After experimenting with this example, restore the old copy of
certmap.conf file.  Or else, set the certmap.conf file as follows:

certmap default default
default:DNComps	    
default:FilterComps	e, mail, uid
default:VerifyCert	on