| 1 |
# BEGIN COPYRIGHT BLOCK |
| 2 |
# Copyright (C) 2001 Sun Microsystems, Inc. Used by permission. |
| 3 |
# Copyright (C) 2005 Red Hat, Inc. |
| 4 |
# All rights reserved. |
| 5 |
# |
| 6 |
# License: GPL (version 3 or any later version). |
| 7 |
# See LICENSE for details. |
| 8 |
# END COPYRIGHT BLOCK |
| 9 |
# |
| 10 |
|
| 11 |
This directory contains an example program to demonstrate |
| 12 |
writing plugins using the "Certificate to LDAP Mapping" API. |
| 13 |
Please read the "Managing Servers" manual to find out |
| 14 |
about how certificate to ldap mapping can be configured using |
| 15 |
the <ServerRoot>/userdb/certmap.conf file. Also refer to the |
| 16 |
"Certificate to LDAP Mapping API" documentation to find out |
| 17 |
about the various API functions and how you can write your |
| 18 |
plugin. |
| 19 |
|
| 20 |
This example demonstrate use of most of the API functions. It |
| 21 |
defines a mapping function, a search function, and a verify |
| 22 |
function. Read the API doc to learn about these functions. |
| 23 |
The init.c file also contains an init function which sets the |
| 24 |
mapping, search and verify functions. |
| 25 |
|
| 26 |
The Mapping Function |
| 27 |
-------------------- |
| 28 |
|
| 29 |
The mapping function extracts the attributes "CN", "E", "O" and |
| 30 |
"C" from the certificate's subject DN using the function |
| 31 |
ldapu_get_cert_ava_val. If the attributes "C" doesn't exists |
| 32 |
then it defaults to "US". It then gets the value of a custom |
| 33 |
certmap.conf property "defaultOU" using the function |
| 34 |
ldapu_certmap_info_attrval. This demonstrates how you can have |
| 35 |
your own custom properties defined in the certmap.conf file. |
| 36 |
The mapping function then returns an ldapdn of the form: |
| 37 |
"cn=<name>, ou=<defaultOU>, o=<o>, c=<c>". |
| 38 |
|
| 39 |
If the "E" attribute has a value, it returns a filter |
| 40 |
"mail=<e>". Finally, the mapping function frees the structures |
| 41 |
returned by some of the API functions it called. |
| 42 |
|
| 43 |
|
| 44 |
The Search Function |
| 45 |
------------------- |
| 46 |
|
| 47 |
The search function calls a dummy function to get the |
| 48 |
certificate's serial number. It then does a subtree search in |
| 49 |
the entire directory for the filter |
| 50 |
"certSerialNumber=<serial No.>". If this fails, it calls the |
| 51 |
default search function. This demonstrates how you can use the |
| 52 |
default functions in your custom functions. |
| 53 |
|
| 54 |
The Verify Function |
| 55 |
------------------- |
| 56 |
|
| 57 |
The verify function returns LDAPU_SUCCESS if only one entry was |
| 58 |
returned by the search function. Otherwise, it returns |
| 59 |
LDAPU_CERT_VERIFY_FUNCTION_FAILED. |
| 60 |
|
| 61 |
|
| 62 |
Error Reporting |
| 63 |
--------------- |
| 64 |
|
| 65 |
To report errors/warning, there is a function defined called |
| 66 |
plugin_ereport. This function demonstrates how to get the |
| 67 |
subject DN and the issuer DN from the certificate. |
| 68 |
|
| 69 |
Build Procedure |
| 70 |
--------------- |
| 71 |
On UNIX: Edit the Makefile, and set the variables ARCH & SROOT |
| 72 |
according to the comments in the Makefile. Download LDAP C SDK |
| 73 |
from the mozilla.org site and make the ldap include |
| 74 |
files available in <SROOT>/include. Copy the |
| 75 |
../include/certmap.h file to the <SROOT>/include directory. |
| 76 |
Use 'gmake' to build the plugin. A shared library plugin.so |
| 77 |
(plugin.sl on HP) will be created in the current directory. |
| 78 |
|
| 79 |
On NT: Execute the following command: |
| 80 |
NMAKE /f "Certmap.mak" CFG="Certmap - Win32 Debug" |
| 81 |
Certmap.dll will be created in the Debug subdirectory. |
| 82 |
|
| 83 |
Certmap.conf Configuration |
| 84 |
-------------------------- |
| 85 |
Save a copy of certmap.conf file. |
| 86 |
Change the certmap.conf file as follows: |
| 87 |
|
| 88 |
certmap default default |
| 89 |
default:defaultOU marketing |
| 90 |
default:library <path to the shared library> |
| 91 |
default:InitFn plugin_init_fn |
| 92 |
|
| 93 |
|
| 94 |
After experimenting with this example, restore the old copy of |
| 95 |
certmap.conf file. Or else, set the certmap.conf file as follows: |
| 96 |
|
| 97 |
certmap default default |
| 98 |
default:DNComps |
| 99 |
default:FilterComps e, mail, uid |
| 100 |
default:VerifyCert on |