Debian Codegraph @

lib/ldaputil/examples/README

raw
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