Debian Codegraph @

lib/ldaputil/ldapu-changes.html

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 <HTML>
10 <HEAD>
11 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
12 <META NAME="Author" CONTENT="Nitin More">
13 <META NAME="GENERATOR" CONTENT="Mozilla/4.01 [en] (WinNT; U) [Netscape]">
14 </HEAD>
15 <BODY>
16
17 <CENTER>
18 <H1>
19 Change Log for the ldaputil library</H1></CENTER>
20
21 <DT>
22 Author: Nitin More</DT>
23
24 <DT>
25 E-mail:&nbsp; <A HREF="mailto:[email protected]">[email protected]</A></DT>
26
27 <DT>
28 Phone: (415) 937-4240</DT>
29
30 <CENTER></CENTER>
31
32 <CENTER>
33 <HR WIDTH="100%"></CENTER>
34
35 <CENTER></CENTER>
36
37 <CENTER><B><FONT SIZE=+1>Changes since Apr 17, 1997</FONT></B></CENTER>
38
39
40 <P>Last Update: Aug 25, 1997
41
42 <P>All the new changes have been checked into the server3_tier_branch.&nbsp;
43 The server3_branch is frozen &amp; contains the version of 'ldaputil' for
44 the SuiteSpot 3.0 release.
45 <H2>
46 Changed:</H2>
47 Several bug fixes went in since I last modified this file.&nbsp; The important
48 ones are:
49 <UL>
50 <LI>
51 <A HREF="http://scopus/bugsplat/show_bug.cgi?id=79373">79373</A>: Attributes
52 listed multiple times in certmap.conf were turining that attribute off
53 and enabling some other attribute.&nbsp; (For example, if you have "E"
54 as well as "MAIL" in FilterComps, they cancelled each other).</LI>
55
56 <LI>
57 <A HREF="http://scopus/bugsplat/show_bug.cgi?id=58474">58474</A>: If nested
58 group checks goes on for 30 recursions, a circular groups error is returned.</LI>
59
60 <LI>
61 <A HREF="http://scopus/bugsplat/show_bug.cgi?id=80004">80004</A>: after
62 thoroughly testing the certmap utility, several (mostly minor) oddities
63 were found &amp; fixed.</LI>
64 </UL>
65
66 <H2>
67 Added:</H2>
68
69 <UL>
70 <LI>
71 <A HREF="http://scopus/bugsplat/show_bug.cgi?id=79370">79370</A>: Group
72 membership check is optimized now through the new function <B>ldapu_auth_userdn_groupids</B>.&nbsp;
73 Use this new function to get the optimization.&nbsp; This function's algorithm
74 is as follows:</LI>
75
76 <BR>The first search uses the following filter (w/o the group names!):
77 <OL><TT>(| (&amp; (objectclass=groupofuniquenames)</TT>
78 <BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (uniquemember=&lt;userDN>))</TT>
79 <BR><TT>&nbsp;&nbsp; (&amp; (objectclass=groupofnames)(member=&lt;userDN>)))</TT>
80 <BR>&nbsp;</OL>
81 This gives us all the groups the user is member of.&nbsp; We ask for only
82 the "CN" attributes of the returned groups.&nbsp; We check if "CN" of any
83 of the returned groups is one of the groups we have.&nbsp; If yes, we have
84 succeeded.&nbsp; If there are no groups returned then we have failed.&nbsp;
85 Otherwise, we continue with the nested group check.&nbsp; To perform that
86 check, we need DNs of all the groups the user is member of, which we already
87 have from the previous search.&nbsp; Now we repeat the search as follows:
88 <OL><TT>(| (&amp; (objectclass=groupofuniquenames)</TT>
89 <BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (| (uniquemember=&lt;grp1DN>)...
90 (uniquemember=&lt;grpNDN>))</TT>
91 <BR><TT>&nbsp;&nbsp; (&amp; (objectclass=groupofnames)</TT>
92 <BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (| (member=&lt;grp1DN>)... (member=&lt;grpNDN>))</TT></OL>
93 We check the list of groups returned by this search with the groups in
94 the ACL and recursively continue until we succeed or no more groups are
95 returned from the searches.
96
97 <P>Advantages of this new function is it checks multiple groups at the
98 same time.&nbsp; Previously we were performing 2 ldap lookups per group.&nbsp;
99 Now we achieve this in a single ldap lookup!
100
101 <P><B><BLINK>Caution</BLINK></B>: this function allows multiple groups
102 with the same "CN".
103
104 <P>To use this function, you need to provide a list of group names in any
105 form (e.g comma separated string, a hash table, array of strings, etc.)
106 and a function to compare the name returned by the ldap lookup with your
107 group names.</UL>
108
109 <CENTER><B><FONT SIZE=+1>Changes since Mar 22, 1997</FONT></B></CENTER>
110
111
112 <P>Last Update: Apr 17, 1997
113
114 <P>Now that all beta releases are out for servers using this library, I
115 could do some incompatible changes to make this library more flexible.
116 No more incompatible changes are planned (except for possibly one: see
117 http://scopus/bugsplat/show_bug.cgi?id=58482). <B><BLINK>All 3.0 SuiteSpot
118 servers supporting client auth need to upgrade to this version.</BLINK></B>
119 <H2>
120 Changed:</H2>
121
122 <UL>
123 <LI>
124 <B>Exchanged certmap.h &amp; ldaputil.h: </B>ldaputil.h had public API
125 but when the file was installed on the server root, it was called certmap.h.
126 Since we already had a certmap.h, this was causing lot of confusion. If
127 you were including "certmap.h", now include "ldaputil.h" and vice versa.</LI>
128
129 <LI>
130 <B>Renamed 'SearchComps' to 'FilterComps'</B>: Shouldn't affect your code
131 but may affect tests and documentation.</LI>
132
133 <LI>
134 <B>'VerifyCert' must be either "on" or "off"</B>: VerifyCert didn't have
135 a value. Now it must have a value. If it has a value of "on" then the "verification"
136 step is on, otherwise it is off.</LI>
137
138 <LI>
139 <B>Important bug fixes</B>: One bug was causing stack corruption &amp;
140 weird unpredictable results. The other important bug was to map 'E' in
141 cert to 'MAIL' in LDAP.</LI>
142 </UL>
143
144 <H2>
145 Added:</H2>
146
147 <UL>
148 <LI>
149 <B>Settable 'search function'</B>: User defined search function can be
150 set for cert to ldap mapping.</LI>
151
152 <LI>
153 <B>ldapu_get_cert_ava_val &amp; ldapu_free_cert_ava_val</B>: API functions
154 to get &amp; free an attribute's value(s) from either the subject DN or
155 the issuer DN from a cert.</LI>
156 </UL>
157
158 <H2>
159 Open Bugs:</H2>
160
161 <UL>Following bugs may not get fixed by RTM.</UL>
162
163 <UL>
164 <LI>
165 <A HREF="http://scopus/bugsplat/show_bug.cgi?id=51279">51279</A>: 'uniquemember'
166 bug</LI>
167
168 <LI>
169 <A HREF="http://scopus/bugsplat/show_bug.cgi?id=58474">58474</A>:&nbsp;
170 'circular groups' results in infinite loop</LI>
171
172 <LI>
173 <A HREF="http://scopus/bugsplat/show_bug.cgi?id=58478">58478</A>: Don't
174 allow a space as a valid delimeter for DNComps &amp; FilterComps.</LI>
175
176 <LI>
177 <A HREF="http://scopus/bugsplat/show_bug.cgi?id=58482">58482</A>: Make
178 the 'search function' configurable.</LI>
179
180 <BR>
181 <HR WIDTH="100%"></UL>
182
183 <CENTER>
184 <H3>
185 Changes since Mar 18, 1997</H3></CENTER>
186
187 <DT>
188 Last Update: Mar 22, 1997</DT>
189
190 <DT>
191 A query on how to map a verisign certificate prompted these changes.&nbsp;
192 I was hoping I don't have to do any major changes when I wrote this document
193 on Mar 18. These are incompatible changes -- please review them before
194 you upgrade.&nbsp; I have checked in this file in CVS under "ns/netsite/lib/ldaputil/ldapu-changes.html".
195 I have added all the "XYZ_branch" and "XYZ_point" tags to this file so
196 that you can easily see this file in your tree.&nbsp; When I make significant
197 changes to this file/library, I will retag this file for your branch to
198 make it same as the server3_branch. [Let me know if I shouldn't do it for
199 your branch].</DT>
200
201 <H2>
202 Changed:</H2>
203
204 <UL>
205 <LI>
206 <B>ldapu_cert_to_ldap_entry</B>: The major change was to allow for the
207 mapped DN to be NULL and in that case, start the search from the basedn
208 of the LDAP server. This required API change so that the basedn can be
209 passed to the ldapu_cert_to_ldap_entry function. This change was required
210 for correctly mapping certs from verisign w/o writing plugins. The Verisign
211 certs can be mapped correctly using the following setting in the &lt;ServerRoot>/userdb/certmap.conf
212 file:</LI>
213
214 <UL><TT><FONT SIZE=+1>certmap verisign &lt;verisign's DN></FONT></TT>
215 <BR><TT><FONT SIZE=+1>verisign:dncomps</FONT></TT>
216 <BR><TT><FONT SIZE=+1>verisign:searchcomps cn, e</FONT></TT></UL>
217 The mapped DN will be NULL so basedn will be used.&nbsp; The filter will
218 be
219 <BR>(&amp; (cn="&lt;user's CN>") (mail="&lt;user's mail>")).&nbsp; The
220 new signature of ldapu_cert_to_ldap_entry is as follows:
221 <BR>&nbsp;&nbsp;&nbsp; int ldapu_cert_to_ldap_entry(void *cert, LDAP *ld,
222 const char *basedn, LDAPMessage **res);
223 <LI>
224 <B>verify cert functions</B>: A major change in how verify cert functions
225 work.&nbsp; This is function is now called even when multiple potential
226 matches are found for the cert.&nbsp; The mapping is successful if the
227 verify function can reduce the number of matches to exactly one.&nbsp;
228 For example, if there are multiple "Joe Smith" entries, at most one of
229 those will have the cert in it's "userCertificate" attr.&nbsp; The verify
230 function will select that entry.&nbsp; The verify function is called with
231 "LDAPMessage *res" containing all the potential matches.&nbsp; It should
232 return a pointer to the matched entry in the new "LDAPMessage **entry"
233 parameter.&nbsp; The new signature for CertVerifyFn_t is as follows:</LI>
234
235 <BR>&nbsp;&nbsp;&nbsp; typedef int (*CertVerifyFn_t)(void *cert, LDAP *ld,
236 LDAPMessage *res,
237 <BR>&nbsp;
238
239 <P>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
240 LDAPMessage **entry);
241 <LI>
242 typedef int (*<B>CertMapInitiFn_t)</B>: Renamed from CertmapInitFn_t.&nbsp;
243 Now this has two extra parameters to make it easy to use it in a plugin.
244 Other API functions require "issuerDN" but this function was called with
245 "LDAPUCertMapInfo_t *certinfo".&nbsp; There was no public API function
246 to get the issuerDN from "certinfo". The new signature for CertMapInitFn_t
247 is as follows:</LI>
248
249 <BR>&nbsp;&nbsp;&nbsp; typedef int (*CertMapInitFn_t)(void *certmap_info,
250 const char *issuerName,
251 <BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
252 const char *issuerDN);
253 <LI>
254 (ldapauth.h) <B>ldapu_auth_* functions:</B> For multiple matches, these
255 functions now return LDAPU_ERR_MULTIPLE_MATCHES instead of LDAPU_FAILED.
256 This change was required to make nested group membership work efficiently
257 and enable the new functionality of verify cert function.</LI>
258 </UL>
259
260 <DT>
261
262 <HR WIDTH="100%"></DT>
263
264 <CENTER>
265 <H3>
266 Changes since Feb 1, 1997</H3></CENTER>
267
268 <DT>
269 Last Update: Mar 18, 1997</DT>
270
271 <DT>
272 There have been several changes to the netsite/lib/ldaputil recently. If
273 you use this library, please start using the latest version of ldaputil
274 on the server3_branch so that all the servers go out with the same API
275 and behavior. Review the changes before you upgrade. If you don't plan
276 to upgrade, please let me know.</DT>
277
278 <H2>
279 Renamed:</H2>
280 Following structures and functions are renamed. But this shouldn't affect
281 you unless you have written a certmap plugin.
282 <DD>
283 <TT><FONT SIZE=+1>struct CertMappingFunction_t ---> CertMapFn_t</FONT></TT></DD>
284
285 <DD>
286 <TT><FONT SIZE=+1>struct CertVerifyFunction_t ---> CertVerifyFn_t</FONT></TT></DD>
287
288 <DD>
289 <TT><FONT SIZE=+1>ldapu_set_cert_mapping_function ---> ldapu_set_cert_mapfn</FONT></TT></DD>
290
291 <DD>
292 <TT><FONT SIZE=+1>ldapu_get_cert_mapping_function ---> ldapu_get_cert_mapfn</FONT></TT></DD>
293
294 <DD>
295 <TT><FONT SIZE=+1>ldapu_set_cert_verify_function ---> ldapu_set_cert_verifyfn</FONT></TT></DD>
296
297 <DD>
298 <TT><FONT SIZE=+1>ldapu_get_cert_verify_function ---> ldapu_get_cert_verifyfn</FONT></TT></DD>
299
300 <H2>
301 Removed: (from .h)</H2>
302 Removed the following functions from .h files. They are still in the .c
303 file as static functions. I don't think these should be public. If you
304 think otherwise, let me know.
305 <DD>
306 <TT><FONT SIZE=+1>ldapu_cert_mapping_function_default</FONT></TT></DD>
307
308 <DD>
309 <TT><FONT SIZE=+1>ldapu_cert_verify_function_default</FONT></TT></DD>
310
311 <DD>
312 <TT><FONT SIZE=+1>ldapu_search_cert_dn</FONT></TT></DD>
313
314 <DD>
315 <TT><FONT SIZE=+1>ldapu_subject_dn_to_ldap_dn</FONT></TT></DD>
316
317 <H2>
318 Changed:</H2>
319 The following changes may affect you. Please review them carefully before
320 you upgrade to the latest version of ldaputil.
321 <UL>
322 <LI>
323 <TT>ldapu_auth_userdn_groupdn</TT> -- added <TT>const char *base</TT> argument
324 for group within group membership check</LI>
325
326 <LI>
327 ldap_init and bind calls using <TT>LDAPDatabase_t *ldb</TT> retry once
328 if the LDAP server is/went down.</LI>
329
330 <LI>
331 <TT>typedef CertVerifyFn_t</TT> has different arguments.</LI>
332
333 <LI>
334 DNs from cert with escaped/quoted characters are correctly handled now.</LI>
335
336 <LI>
337 cert to ldap entry mapping is optimized by not using string comparisons
338 during thruntime. A bitmask is created when the config file is read, cert
339 data is mapped to bits and compared against the bitmask.</LI>
340
341 <LI>
342 Only the required attrs are retrieved in most <TT>ldap_search_s </TT>calls
343 from ldaputil. Some new functions were added to keep older functions the
344 same.</LI>
345
346 <LI>
347 Fixed a core dump in ldapu_free_LDAPDatabase_t when using the local db.</LI>
348
349 <LI>
350 ldaputil functions for initializing connection to the LDAP server and binding
351 to the server are thread-safe now. This requires linking to netsite/lib/base.
352 If you don't use libbase, you can turn off the thread-safe code using a
353 compile time option.</LI>
354 </UL>
355
356 <H2>
357 Added:</H2>
358
359 <UL>
360 <LI>
361 Documentation to functions in ldaputil.h (customer API) - ldaputil.h is
362 the external public API for customers to write there plugins.</LI>
363
364 <LI>
365 <TT>ldapu_get_cert_der</TT> - returns raw DER encoded cert data</LI>
366
367 <LI>
368 <TT>ldapu_cert_to_user</TT> - Similar to ldapu_cert_to_ldap_entry but only
369 retrieves the 'uid' and 'userCertificate' attributes from LDAP and also
370 extracts the user id.</LI>
371
372 <LI>
373 <TT>ldapu_find_uid_attrs</TT> and <TT>ldapu_find_group_attrs</TT> - Similar
374 to ldapu_find_uid and ldapu_find_group resp., but only retrieves the specified
375 attributes. Internally used during password verification and group membership
376 checks.</LI>
377
378 <LI>
379 <TT>ldapu_certinfo_delete, ldapu_certinfo_modify and ldapu_certinfo_save</TT>
380 - API for the certmap config file GUI tool which is not yet developed.
381 Any volunteers?</LI>
382 </UL>
383
384 <H2>
385 <FONT SIZE=+1>TODO/Bugs:</FONT></H2>
386
387 <UL>
388 <LI>
389 uniquemember attribute is not handled correctly in the group membership
390 check. If the user's entry has 'x500UniqueIdentifier' attribute populated,
391 the group could refer to the user entry by the user's dn followed by '#'
392 and an unique identifier. For example, the group entry could have:</LI>
393
394 <DD>
395 uniquemember: cn=Joe Smith,o=Netscape,c=US#jsmith</DD>
396
397 <DT>
398 where, 'jsmith' is one of the values of the 'x500UniqueIdentifier' attribute
399 for the Joe Smith entry.</DT>
400
401 <DT>
402 </DT>
403 </UL>
404
405 </BODY>
406 </HTML>