]> git.sur5r.net Git - openldap/blob - servers/slapd/back-ldap/bind.c
save 1 function call...
[openldap] / servers / slapd / back-ldap / bind.c
1 /* bind.c - ldap backend bind function */
2 /* $OpenLDAP$ */
3 /* This work is part of OpenLDAP Software <http://www.openldap.org/>.
4  *
5  * Copyright 1999-2005 The OpenLDAP Foundation.
6  * Portions Copyright 2000-2003 Pierangelo Masarati.
7  * Portions Copyright 1999-2003 Howard Chu.
8  * All rights reserved.
9  *
10  * Redistribution and use in source and binary forms, with or without
11  * modification, are permitted only as authorized by the OpenLDAP
12  * Public License.
13  *
14  * A copy of this license is available in the file LICENSE in the
15  * top-level directory of the distribution or, alternatively, at
16  * <http://www.OpenLDAP.org/license.html>.
17  */
18 /* ACKNOWLEDGEMENTS:
19  * This work was initially developed by Howard Chu for inclusion
20  * in OpenLDAP Software and subsequently enhanced by Pierangelo
21  * Masarati.
22  */
23
24 #include "portable.h"
25
26 #include <stdio.h>
27
28 #include <ac/errno.h>
29 #include <ac/socket.h>
30 #include <ac/string.h>
31
32 #define AVL_INTERNAL
33 #include "slap.h"
34 #include "back-ldap.h"
35
36 #include <lutil_ldap.h>
37
38 #define PRINT_CONNTREE 0
39
40 static LDAP_REBIND_PROC ldap_back_rebind;
41
42 static int
43 ldap_back_proxy_authz_bind( struct ldapconn *lc, Operation *op, SlapReply *rs );
44
45 static int
46 ldap_back_prepare_conn( struct ldapconn **lcp, Operation *op, SlapReply *rs, ldap_back_send_t sendok );
47
48 int
49 ldap_back_bind( Operation *op, SlapReply *rs )
50 {
51         struct ldapinfo *li = (struct ldapinfo *) op->o_bd->be_private;
52         struct ldapconn *lc;
53
54         int rc = 0;
55         ber_int_t msgid;
56
57         lc = ldap_back_getconn( op, rs, LDAP_BACK_SENDERR );
58         if ( !lc ) {
59                 return rs->sr_err;
60         }
61
62         if ( !BER_BVISNULL( &lc->lc_bound_ndn ) ) {
63                 ch_free( lc->lc_bound_ndn.bv_val );
64                 BER_BVZERO( &lc->lc_bound_ndn );
65         }
66         lc->lc_bound = 0;
67
68         /* method is always LDAP_AUTH_SIMPLE if we got here */
69         rs->sr_err = ldap_sasl_bind( lc->lc_ld, op->o_req_dn.bv_val,
70                         LDAP_SASL_SIMPLE,
71                         &op->orb_cred, op->o_ctrls, NULL, &msgid );
72         rc = ldap_back_op_result( lc, op, rs, msgid, LDAP_BACK_SENDERR );
73
74         if ( rc == LDAP_SUCCESS ) {
75                 /* If defined, proxyAuthz will be used also when
76                  * back-ldap is the authorizing backend; for this
77                  * purpose, a successful bind is followed by a
78                  * bind with the configured identity assertion */
79                 /* NOTE: use with care */
80                 if ( li->idassert_flags & LDAP_BACK_AUTH_OVERRIDE ) {
81                         ldap_back_proxy_authz_bind( lc, op, rs );
82                         if ( lc->lc_bound == 0 ) {
83                                 rc = 1;
84                                 goto done;
85                         }
86                 }
87
88                 lc->lc_bound = 1;
89                 ber_dupbv( &lc->lc_bound_ndn, &op->o_req_ndn );
90
91                 if ( LDAP_BACK_SAVECRED( li ) ) {
92                         if ( !BER_BVISNULL( &lc->lc_cred ) ) {
93                                 memset( lc->lc_cred.bv_val, 0,
94                                                 lc->lc_cred.bv_len );
95                         }
96                         ber_bvreplace( &lc->lc_cred, &op->orb_cred );
97                         ldap_set_rebind_proc( lc->lc_ld, ldap_back_rebind, lc );
98                 }
99         }
100 done:;
101
102         /* must re-insert if local DN changed as result of bind */
103         if ( lc->lc_bound && !dn_match( &op->o_req_ndn, &lc->lc_local_ndn ) ) {
104                 int             lerr;
105
106                 /* wait for all other ops to release the connection */
107 retry_lock:;
108                 switch ( ldap_pvt_thread_mutex_trylock( &li->conn_mutex ) ) {
109                 case LDAP_PVT_THREAD_EBUSY:
110                 default:
111                         ldap_pvt_thread_yield();
112                         goto retry_lock;
113
114                 case 0:
115                         if ( lc->lc_refcnt > 1 ) {
116                                 ldap_pvt_thread_mutex_unlock( &li->conn_mutex );
117                                 ldap_pvt_thread_yield();
118                                 goto retry_lock;
119                         }
120                         break;
121                 }
122
123                 assert( lc->lc_refcnt == 1 );
124                 lc = avl_delete( &li->conntree, (caddr_t)lc,
125                                 ldap_back_conn_cmp );
126                 assert( lc != NULL );
127
128                 ber_bvreplace( &lc->lc_local_ndn, &op->o_req_ndn );
129                 lerr = avl_insert( &li->conntree, (caddr_t)lc,
130                         ldap_back_conn_cmp, ldap_back_conn_dup );
131                 ldap_pvt_thread_mutex_unlock( &li->conn_mutex );
132                 if ( lerr == -1 ) {
133                         /* we can do this because lc_refcnt == 1 */
134                         ldap_back_conn_free( lc );
135                         lc = NULL;
136                 }
137         }
138
139         if ( lc != NULL ) {
140                 ldap_back_release_conn( op, rs, lc );
141         }
142
143         return( rc );
144 }
145
146 /*
147  * ldap_back_conn_cmp
148  *
149  * compares two struct ldapconn based on the value of the conn pointer;
150  * used by avl stuff
151  */
152 int
153 ldap_back_conn_cmp( const void *c1, const void *c2 )
154 {
155         const struct ldapconn *lc1 = (const struct ldapconn *)c1;
156         const struct ldapconn *lc2 = (const struct ldapconn *)c2;
157         int rc;
158
159         /* If local DNs don't match, it is definitely not a match */
160         rc = ber_bvcmp( &lc1->lc_local_ndn, &lc2->lc_local_ndn );
161         if ( rc ) {
162                 return rc;
163         }
164
165         /* For shared sessions, conn is NULL. Only explicitly
166          * bound sessions will have non-NULL conn.
167          */
168         return SLAP_PTRCMP( lc1->lc_conn, lc2->lc_conn );
169 }
170
171 /*
172  * ldap_back_conn_dup
173  *
174  * returns -1 in case a duplicate struct ldapconn has been inserted;
175  * used by avl stuff
176  */
177 int
178 ldap_back_conn_dup( void *c1, void *c2 )
179 {
180         struct ldapconn *lc1 = (struct ldapconn *)c1;
181         struct ldapconn *lc2 = (struct ldapconn *)c2;
182
183         /* Cannot have more than one shared session with same DN */
184         if ( dn_match( &lc1->lc_local_ndn, &lc2->lc_local_ndn ) &&
185                         lc1->lc_conn == lc2->lc_conn )
186         {
187                 return -1;
188         }
189                 
190         return 0;
191 }
192
193 #if PRINT_CONNTREE > 0
194 static void
195 ravl_print( Avlnode *root, int depth )
196 {
197         int     i;
198         struct ldapconn *lc;
199         
200         if ( root == 0 ) {
201                 return;
202         }
203         
204         ravl_print( root->avl_right, depth+1 );
205         
206         for ( i = 0; i < depth; i++ ) {
207                 printf( "   " );
208         }
209
210         lc = root->avl_data;
211         printf( "lc(%lx) local(%s) conn(%lx) %d\n",
212                         lc, lc->lc_local_ndn.bv_val, lc->lc_conn, root->avl_bf );
213         
214         ravl_print( root->avl_left, depth+1 );
215 }
216
217 static void
218 myprint( Avlnode *root )
219 {
220         printf( "********\n" );
221         
222         if ( root == 0 ) {
223                 printf( "\tNULL\n" );
224
225         } else {
226                 ravl_print( root, 0 );
227         }
228         
229         printf( "********\n" );
230 }
231 #endif /* PRINT_CONNTREE */
232
233 int
234 ldap_back_freeconn( Operation *op, struct ldapconn *lc )
235 {
236         struct ldapinfo *li = (struct ldapinfo *) op->o_bd->be_private;
237
238 retry_lock:;
239         switch ( ldap_pvt_thread_mutex_trylock( &li->conn_mutex ) ) {
240         case LDAP_PVT_THREAD_EBUSY:
241         default:
242                 ldap_pvt_thread_yield();
243                 goto retry_lock;
244
245         case 0:
246                 break;
247         }
248
249         assert( lc->lc_refcnt > 0 );
250         if ( --lc->lc_refcnt == 0 ) {
251                 lc = avl_delete( &li->conntree, (caddr_t)lc,
252                                 ldap_back_conn_cmp );
253                 assert( lc != NULL );
254
255                 ldap_back_conn_free( (void *)lc );
256         }
257
258         ldap_pvt_thread_mutex_unlock( &li->conn_mutex );
259
260         return 0;
261 }
262
263 static int
264 ldap_back_prepare_conn( struct ldapconn **lcp, Operation *op, SlapReply *rs, ldap_back_send_t sendok )
265 {
266         struct ldapinfo *li = (struct ldapinfo *)op->o_bd->be_private;
267         int             vers = op->o_protocol;
268         LDAP            *ld = NULL;
269
270         assert( lcp != NULL );
271
272         rs->sr_err = ldap_initialize( &ld, li->url );
273         if ( rs->sr_err != LDAP_SUCCESS ) {
274                 goto error_return;
275         }
276
277         /* Set LDAP version. This will always succeed: If the client
278          * bound with a particular version, then so can we.
279          */
280         ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, (const void *)&vers );
281
282         /* automatically chase referrals ("[dont-]chase-referrals" statement) */
283         if ( LDAP_BACK_CHASE_REFERRALS( li ) ) {
284                 ldap_set_option( ld, LDAP_OPT_REFERRALS, LDAP_OPT_ON );
285         }
286
287 #ifdef HAVE_TLS
288         /* start TLS ("tls-[try-]{start,propagate}" statements) */
289         if ( ( LDAP_BACK_USE_TLS( li ) || ( op->o_conn->c_is_tls && LDAP_BACK_PROPAGATE_TLS( li ) ) )
290                                 && !ldap_is_ldaps_url( li->url ) )
291         {
292 #ifdef SLAP_STARTTLS_ASYNCHRONOUS
293                 /*
294                  * use asynchronous StartTLS
295                  * in case, chase referral (not implemented yet)
296                  */
297                 int             msgid;
298
299                 rs->sr_err = ldap_start_tls( ld, NULL, NULL, &msgid );
300                 if ( rs->sr_err == LDAP_SUCCESS ) {
301                         LDAPMessage     *res = NULL;
302                         int             rc, retries = 1;
303                         struct timeval  tv = { 0, 0 };
304
305 retry:;
306                         rc = ldap_result( ld, msgid, LDAP_MSG_ALL, &tv, &res );
307                         if ( rc < 0 ) {
308                                 rs->sr_err = LDAP_OTHER;
309
310                         } else if ( rc == 0 ) {
311                                 if ( retries ) {
312                                         retries--;
313                                         tv.tv_sec = 0;
314                                         tv.tv_usec = 100000;
315                                         goto retry;
316                                 }
317                                 rs->sr_err = LDAP_OTHER;
318
319                         } else if ( rc == LDAP_RES_EXTENDED ) {
320                                 struct berval   *data = NULL;
321
322                                 rs->sr_err = ldap_parse_extended_result( ld, res,
323                                                 NULL, &data, 0 );
324                                 if ( rs->sr_err == LDAP_SUCCESS ) {
325                                         rs->sr_err = ldap_result2error( ld, res, 1 );
326                                         res = NULL;
327                                         
328                                         /* FIXME: in case a referral 
329                                          * is returned, should we try
330                                          * using it instead of the 
331                                          * configured URI? */
332                                         if ( rs->sr_err == LDAP_SUCCESS ) {
333                                                 ldap_install_tls( ld );
334
335                                         } else if ( rs->sr_err == LDAP_REFERRAL ) {
336                                                 rs->sr_err = LDAP_OTHER;
337                                                 rs->sr_text = "unwilling to chase referral returned by Start TLS exop";
338                                         }
339
340                                         if ( data ) {
341                                                 if ( data->bv_val ) {
342                                                         ber_memfree( data->bv_val );
343                                                 }
344                                                 ber_memfree( data );
345                                         }
346                                 }
347
348                         } else {
349                                 rs->sr_err = LDAP_OTHER;
350                         }
351
352                         if ( res != NULL ) {
353                                 ldap_msgfree( res );
354                         }
355                 }
356 #else /* ! SLAP_STARTTLS_ASYNCHRONOUS */
357                 /*
358                  * use synchronous StartTLS
359                  */
360                 rs->sr_err = ldap_start_tls_s( ld, NULL, NULL );
361 #endif /* ! SLAP_STARTTLS_ASYNCHRONOUS */
362
363                 /* if StartTLS is requested, only attempt it if the URL
364                  * is not "ldaps://"; this may occur not only in case
365                  * of misconfiguration, but also when used in the chain 
366                  * overlay, where the "uri" can be parsed out of a referral */
367                 if ( rs->sr_err == LDAP_SERVER_DOWN
368                                 || ( rs->sr_err != LDAP_SUCCESS && LDAP_BACK_TLS_CRITICAL( li ) ) )
369                 {
370                         ldap_unbind_ext( ld, NULL, NULL );
371                         goto error_return;
372                 }
373
374                 /* in case Start TLS is not critical */
375                 rs->sr_err = LDAP_SUCCESS;
376         }
377 #endif /* HAVE_TLS */
378
379         if ( *lcp == NULL ) {
380                 *lcp = (struct ldapconn *)ch_calloc( 1, sizeof( struct ldapconn ) );
381         }
382         (*lcp)->lc_ld = ld;
383         (*lcp)->lc_refcnt = 1;
384
385 error_return:;
386         if ( rs->sr_err != LDAP_SUCCESS ) {
387                 rs->sr_err = slap_map_api2result( rs );
388                 if ( sendok & LDAP_BACK_SENDERR ) {
389                         if ( rs->sr_text == NULL ) {
390                                 rs->sr_text = "ldap_initialize() failed";
391                         }
392                         send_ldap_result( op, rs );
393                         rs->sr_text = NULL;
394                 }
395         }
396
397         return rs->sr_err;
398 }
399
400 struct ldapconn *
401 ldap_back_getconn( Operation *op, SlapReply *rs, ldap_back_send_t sendok )
402 {
403         struct ldapinfo *li = (struct ldapinfo *)op->o_bd->be_private;
404         struct ldapconn *lc,
405                         lc_curr = { 0 };
406         int             refcnt = 1;
407
408         /* Searches for a ldapconn in the avl tree */
409
410         /* Explicit binds must not be shared */
411         if ( op->o_tag == LDAP_REQ_BIND
412                 || ( op->o_conn
413                         && op->o_conn->c_authz_backend
414                         && op->o_bd->be_private == op->o_conn->c_authz_backend->be_private ) )
415         {
416                 lc_curr.lc_conn = op->o_conn;
417
418         } else {
419                 lc_curr.lc_conn = NULL;
420         }
421         
422         /* Internal searches are privileged and shared. So is root. */
423         /* FIXME: there seem to be concurrency issues */
424         if ( op->o_do_not_cache || be_isroot( op ) ) {
425                 lc_curr.lc_local_ndn = op->o_bd->be_rootndn;
426                 lc_curr.lc_conn = NULL;
427                 lc_curr.lc_ispriv = 1;
428
429         } else {
430                 lc_curr.lc_local_ndn = op->o_ndn;
431         }
432
433 retry_lock:;
434         switch ( ldap_pvt_thread_mutex_trylock( &li->conn_mutex ) ) {
435         case LDAP_PVT_THREAD_EBUSY:
436         default:
437                 ldap_pvt_thread_yield();
438                 goto retry_lock;
439
440         case 0:
441                 break;
442         }
443
444         lc = (struct ldapconn *)avl_find( li->conntree, 
445                         (caddr_t)&lc_curr, ldap_back_conn_cmp );
446         if ( lc != NULL ) {
447                 refcnt = ++lc->lc_refcnt;
448         }
449         ldap_pvt_thread_mutex_unlock( &li->conn_mutex );
450
451         /* Looks like we didn't get a bind. Open a new session... */
452         if ( lc == NULL ) {
453                 if ( ldap_back_prepare_conn( &lc, op, rs, sendok ) != LDAP_SUCCESS ) {
454                         return NULL;
455                 }
456
457                 lc->lc_conn = lc_curr.lc_conn;
458                 ber_dupbv( &lc->lc_local_ndn, &lc_curr.lc_local_ndn );
459
460                 ldap_pvt_thread_mutex_init( &lc->lc_mutex );
461
462                 if ( lc_curr.lc_ispriv ) {
463                         ber_dupbv( &lc->lc_cred, &li->acl_passwd );
464                         ber_dupbv( &lc->lc_bound_ndn, &li->acl_authcDN );
465                         lc->lc_ispriv = lc_curr.lc_ispriv;
466
467                 } else {
468                         BER_BVZERO( &lc->lc_cred );
469                         BER_BVZERO( &lc->lc_bound_ndn );
470                         if ( op->o_conn && !BER_BVISEMPTY( &op->o_ndn )
471                                 && op->o_bd->be_private == op->o_conn->c_authz_backend->be_private )
472                         {
473                                 ber_dupbv( &lc->lc_bound_ndn, &op->o_ndn );
474                         }
475                 }
476
477                 lc->lc_bound = 0;
478
479                 /* Inserts the newly created ldapconn in the avl tree */
480 retry_lock2:;
481                 switch ( ldap_pvt_thread_mutex_trylock( &li->conn_mutex ) ) {
482                 case LDAP_PVT_THREAD_EBUSY:
483                 default:
484                         ldap_pvt_thread_yield();
485                         goto retry_lock2;
486
487                 case 0:
488                         break;
489                 }
490
491                 assert( lc->lc_refcnt == 1 );
492                 rs->sr_err = avl_insert( &li->conntree, (caddr_t)lc,
493                         ldap_back_conn_cmp, ldap_back_conn_dup );
494
495 #if PRINT_CONNTREE > 0
496                 myprint( li->conntree );
497 #endif /* PRINT_CONNTREE */
498         
499                 ldap_pvt_thread_mutex_unlock( &li->conn_mutex );
500
501                 Debug( LDAP_DEBUG_TRACE,
502                         "=>ldap_back_getconn: conn %p inserted (refcnt=%u)\n",
503                         (void *)lc, refcnt, 0 );
504         
505                 /* Err could be -1 in case a duplicate ldapconn is inserted */
506                 if ( rs->sr_err != 0 ) {
507                         ldap_back_conn_free( lc );
508                         rs->sr_err = LDAP_OTHER;
509                         if ( op->o_conn && ( sendok & LDAP_BACK_SENDERR ) ) {
510                                 send_ldap_error( op, rs, LDAP_OTHER,
511                                         "internal server error" );
512                         }
513                         return NULL;
514                 }
515
516         } else {
517                 Debug( LDAP_DEBUG_TRACE,
518                         "=>ldap_back_getconn: conn %p fetched (refcnt=%u)\n",
519                         (void *)lc, refcnt, 0 );
520         }
521         
522         return lc;
523 }
524
525 void
526 ldap_back_release_conn(
527         Operation               *op,
528         SlapReply               *rs,
529         struct ldapconn         *lc )
530 {
531         struct ldapinfo *li = (struct ldapinfo *)op->o_bd->be_private;
532
533 retry_lock:;
534         switch ( ldap_pvt_thread_mutex_trylock( &li->conn_mutex ) ) {
535         case LDAP_PVT_THREAD_EBUSY:
536         default:
537                 ldap_pvt_thread_yield();
538                 goto retry_lock;
539
540         case 0:
541                 break;
542         }
543
544         assert( lc->lc_refcnt > 0 );
545         lc->lc_refcnt--;
546         ldap_pvt_thread_mutex_unlock( &li->conn_mutex );
547 }
548
549 /*
550  * ldap_back_dobind
551  *
552  * Note: as the check for the value of lc->lc_bound was already here, I removed
553  * it from all the callers, and I made the function return the flag, so
554  * it can be used to simplify the check.
555  *
556  * Note: lc_mutex is locked; dolock indicates whether li->conn_mutex
557  * must be locked or not
558  */
559 static int
560 ldap_back_dobind_int(
561         struct ldapconn         *lc,
562         Operation               *op,
563         SlapReply               *rs,
564         ldap_back_send_t        sendok,
565         int                     retries,
566         int                     dolock )
567 {       
568         int             rc;
569         ber_int_t       msgid;
570
571         assert( retries >= 0 );
572
573         if ( !lc->lc_bound ) {
574                 struct ldapinfo *li = (struct ldapinfo *)op->o_bd->be_private;
575
576                 /*
577                  * FIXME: we need to let clients use proxyAuthz
578                  * otherwise we cannot do symmetric pools of servers;
579                  * we have to live with the fact that a user can
580                  * authorize itself as any ID that is allowed
581                  * by the authzTo directive of the "proxyauthzdn".
582                  */
583                 /*
584                  * NOTE: current Proxy Authorization specification
585                  * and implementation do not allow proxy authorization
586                  * control to be provided with Bind requests
587                  */
588                 /*
589                  * if no bind took place yet, but the connection is bound
590                  * and the "idassert-authcDN" (or other ID) is set, 
591                  * then bind as the asserting identity and explicitly 
592                  * add the proxyAuthz control to every operation with the
593                  * dn bound to the connection as control value.
594                  * This is done also if this is the authrizing backend,
595                  * but the "override" flag is given to idassert.
596                  * It allows to use SASL bind and yet proxyAuthz users
597                  */
598                 if ( op->o_conn != NULL &&
599                                 !op->o_do_not_cache &&
600                                 ( BER_BVISNULL( &lc->lc_bound_ndn ) ||
601                                   ( li->idassert_flags & LDAP_BACK_AUTH_OVERRIDE ) ) )
602                 {
603                         (void)ldap_back_proxy_authz_bind( lc, op, rs );
604                         goto done;
605                 }
606
607 #ifdef HAVE_CYRUS_SASL
608                 if ( lc->lc_ispriv && li->acl_authmethod == LDAP_AUTH_SASL ) {
609                         void            *defaults = NULL;
610
611 #if 1   /* will deal with this later... */
612                         if ( li->acl_secprops != NULL ) {
613                                 rc = ldap_set_option( lc->lc_ld,
614                                         LDAP_OPT_X_SASL_SECPROPS, li->acl_secprops);
615
616                                 if( rc != LDAP_OPT_SUCCESS ) {
617                                         Debug( LDAP_DEBUG_ANY, "Error: ldap_set_option "
618                                                 "(%s,SECPROPS,\"%s\") failed!\n",
619                                                 li->url, li->acl_secprops, 0 );
620                                         goto done;
621                                 }
622                         }
623 #endif
624
625                         defaults = lutil_sasl_defaults( lc->lc_ld,
626                                         li->acl_sasl_mech.bv_val,
627                                         li->acl_sasl_realm.bv_val,
628                                         li->acl_authcID.bv_val,
629                                         li->acl_passwd.bv_val,
630                                         NULL );
631
632                         rs->sr_err = ldap_sasl_interactive_bind_s( lc->lc_ld,
633                                         li->acl_authcDN.bv_val,
634                                         li->acl_sasl_mech.bv_val, NULL, NULL,
635                                         LDAP_SASL_QUIET, lutil_sasl_interact,
636                                         defaults );
637
638                         lutil_sasl_freedefs( defaults );
639
640                         rs->sr_err = slap_map_api2result( rs );
641                         if ( rs->sr_err != LDAP_SUCCESS ) {
642                                 lc->lc_bound = 0;
643                                 send_ldap_result( op, rs );
644
645                         } else {
646                                 lc->lc_bound = 1;
647                         }
648                         goto done;
649                 }
650 #endif /* HAVE_CYRUS_SASL */
651
652 retry:;
653                 rs->sr_err = ldap_sasl_bind( lc->lc_ld,
654                                 lc->lc_bound_ndn.bv_val,
655                                 LDAP_SASL_SIMPLE, &lc->lc_cred,
656                                 NULL, NULL, &msgid );
657
658                 if ( rs->sr_err == LDAP_SERVER_DOWN ) {
659                         if ( retries > 0 ) {
660                                 if ( dolock ) {
661 retry_lock:;
662                                         switch ( ldap_pvt_thread_mutex_trylock( &li->conn_mutex ) ) {
663                                         case LDAP_PVT_THREAD_EBUSY:
664                                         default:
665                                                 ldap_pvt_thread_yield();
666                                                 goto retry_lock;
667
668                                         case 0:
669                                                 break;
670                                         }
671                                 }
672
673                                 assert( lc->lc_refcnt > 0 );
674                                 if ( lc->lc_refcnt == 1 ) {
675                                         ldap_unbind_ext( lc->lc_ld, NULL, NULL );
676                                         lc->lc_ld = NULL;
677
678                                         /* lc here must be the regular lc, reset and ready for init */
679                                         rs->sr_err = ldap_back_prepare_conn( &lc, op, rs, sendok );
680                                 }
681                                 if ( dolock ) {
682                                         ldap_pvt_thread_mutex_unlock( &li->conn_mutex );
683                                 }
684                                 if ( rs->sr_err == LDAP_SUCCESS ) {
685                                         retries--;
686                                         goto retry;
687                                 }
688                         }
689
690                         ldap_back_freeconn( op, lc );
691                         rs->sr_err = slap_map_api2result( rs );
692
693                         return 0;
694                 }
695
696                 rc = ldap_back_op_result( lc, op, rs, msgid, sendok );
697                 if ( rc == LDAP_SUCCESS ) {
698                         lc->lc_bound = 1;
699                 }
700         }
701
702 done:;
703         rc = lc->lc_bound;
704         return rc;
705 }
706
707 int
708 ldap_back_dobind( struct ldapconn *lc, Operation *op, SlapReply *rs, ldap_back_send_t sendok )
709 {
710         int     rc;
711
712         ldap_pvt_thread_mutex_lock( &lc->lc_mutex );
713         rc = ldap_back_dobind_int( lc, op, rs, sendok, 1, 1 );
714         ldap_pvt_thread_mutex_unlock( &lc->lc_mutex );
715
716         return rc;
717 }
718
719 /*
720  * ldap_back_rebind
721  *
722  * This is a callback used for chasing referrals using the same
723  * credentials as the original user on this session.
724  */
725 static int 
726 ldap_back_rebind( LDAP *ld, LDAP_CONST char *url, ber_tag_t request,
727         ber_int_t msgid, void *params )
728 {
729         struct ldapconn *lc = (struct ldapconn *)params;
730
731         /* FIXME: add checks on the URL/identity? */
732
733         return ldap_sasl_bind_s( ld, lc->lc_bound_ndn.bv_val,
734                         LDAP_SASL_SIMPLE, &lc->lc_cred, NULL, NULL, NULL );
735 }
736
737 int
738 ldap_back_op_result(
739                 struct ldapconn         *lc,
740                 Operation               *op,
741                 SlapReply               *rs,
742                 ber_int_t               msgid,
743                 ldap_back_send_t        sendok )
744 {
745         char            *match = NULL;
746         LDAPMessage     *res = NULL;
747         char            *text = NULL;
748
749 #define ERR_OK(err) ((err) == LDAP_SUCCESS || (err) == LDAP_COMPARE_FALSE || (err) == LDAP_COMPARE_TRUE)
750
751         rs->sr_text = NULL;
752         rs->sr_matched = NULL;
753
754         /* if the error recorded in the reply corresponds
755          * to a successful state, get the error from the
756          * remote server response */
757         if ( ERR_OK( rs->sr_err ) ) {
758                 int             rc;
759                 struct timeval  tv = { 0, 0 };
760
761 retry:;
762                 /* if result parsing fails, note the failure reason */
763                 switch ( ldap_result( lc->lc_ld, msgid, 1, &tv, &res ) ) {
764                 case 0:
765                         tv.tv_sec = 0;
766                         tv.tv_usec = 100000;    /* 0.1 s */
767                         ldap_pvt_thread_yield();
768                         goto retry;
769
770                 case -1:
771                         ldap_get_option( lc->lc_ld, LDAP_OPT_ERROR_NUMBER,
772                                         &rs->sr_err );
773                         break;
774
775
776                 /* otherwise get the result; if it is not
777                  * LDAP_SUCCESS, record it in the reply
778                  * structure (this includes 
779                  * LDAP_COMPARE_{TRUE|FALSE}) */
780                 default:
781                         rc = ldap_parse_result( lc->lc_ld, res, &rs->sr_err,
782                                         &match, &text, NULL, NULL, 1 );
783                         rs->sr_text = text;
784                         if ( rc != LDAP_SUCCESS ) {
785                                 rs->sr_err = rc;
786                         }
787                 }
788         }
789
790         /* if the error in the reply structure is not
791          * LDAP_SUCCESS, try to map it from client 
792          * to server error */
793         if ( !ERR_OK( rs->sr_err ) ) {
794                 rs->sr_err = slap_map_api2result( rs );
795
796                 /* internal ops ( op->o_conn == NULL ) 
797                  * must not reply to client */
798                 if ( op->o_conn && !op->o_do_not_cache && match ) {
799
800                         /* record the (massaged) matched
801                          * DN into the reply structure */
802                         rs->sr_matched = match;
803                 }
804         }
805         if ( op->o_conn &&
806                         ( ( sendok & LDAP_BACK_SENDOK ) 
807                           || ( ( sendok & LDAP_BACK_SENDERR ) && rs->sr_err != LDAP_SUCCESS ) ) )
808         {
809                 send_ldap_result( op, rs );
810         }
811         if ( match ) {
812                 if ( rs->sr_matched != match ) {
813                         free( (char *)rs->sr_matched );
814                 }
815                 rs->sr_matched = NULL;
816                 ldap_memfree( match );
817         }
818         if ( text ) {
819                 ldap_memfree( text );
820         }
821         rs->sr_text = NULL;
822         return( ERR_OK( rs->sr_err ) ? 0 : -1 );
823 }
824
825 /* return true if bound, false if failed */
826 int
827 ldap_back_retry( struct ldapconn *lc, Operation *op, SlapReply *rs, ldap_back_send_t sendok )
828 {
829         int             rc = 0;
830         struct ldapinfo *li = (struct ldapinfo *)op->o_bd->be_private;
831         
832 retry_lock:;
833         switch ( ldap_pvt_thread_mutex_trylock( &li->conn_mutex ) ) {
834         case LDAP_PVT_THREAD_EBUSY:
835         default:
836                 ldap_pvt_thread_yield();
837                 goto retry_lock;
838
839         case 0:
840                 break;
841         }
842
843         if ( lc->lc_refcnt == 1 ) {
844                 ldap_unbind_ext( lc->lc_ld, NULL, NULL );
845                 lc->lc_ld = NULL;
846                 lc->lc_bound = 0;
847
848                 /* lc here must be the regular lc, reset and ready for init */
849                 rc = ldap_back_prepare_conn( &lc, op, rs, sendok );
850                 if ( rc == LDAP_SUCCESS ) {
851                         rc = ldap_back_dobind_int( lc, op, rs, sendok, 0, 0 );
852                 }
853         }
854
855         ldap_pvt_thread_mutex_unlock( &li->conn_mutex );
856
857         return rc;
858 }
859
860 static int
861 ldap_back_proxy_authz_bind( struct ldapconn *lc, Operation *op, SlapReply *rs )
862 {
863         struct ldapinfo *li = (struct ldapinfo *)op->o_bd->be_private;
864         struct berval   binddn = slap_empty_bv;
865         struct berval   bindcred = slap_empty_bv;
866         int             dobind = 0;
867         int             msgid;
868         int             rc;
869
870         /*
871          * FIXME: we need to let clients use proxyAuthz
872          * otherwise we cannot do symmetric pools of servers;
873          * we have to live with the fact that a user can
874          * authorize itself as any ID that is allowed
875          * by the authzTo directive of the "proxyauthzdn".
876          */
877         /*
878          * NOTE: current Proxy Authorization specification
879          * and implementation do not allow proxy authorization
880          * control to be provided with Bind requests
881          */
882         /*
883          * if no bind took place yet, but the connection is bound
884          * and the "proxyauthzdn" is set, then bind as 
885          * "proxyauthzdn" and explicitly add the proxyAuthz 
886          * control to every operation with the dn bound 
887          * to the connection as control value.
888          */
889
890         /* bind as proxyauthzdn only if no idassert mode
891          * is requested, or if the client's identity
892          * is authorized */
893         switch ( li->idassert_mode ) {
894         case LDAP_BACK_IDASSERT_LEGACY:
895                 if ( !BER_BVISNULL( &op->o_conn->c_ndn ) && !BER_BVISEMPTY( &op->o_conn->c_ndn ) ) {
896                         if ( !BER_BVISNULL( &li->idassert_authcDN ) && !BER_BVISEMPTY( &li->idassert_authcDN ) )
897                         {
898                                 binddn = li->idassert_authcDN;
899                                 bindcred = li->idassert_passwd;
900                                 dobind = 1;
901                         }
902                 }
903                 break;
904
905         default:
906                 /* NOTE: rootdn can always idassert */
907                 if ( li->idassert_authz && !be_isroot( op ) ) {
908                         struct berval authcDN;
909
910                         if ( BER_BVISNULL( &op->o_conn->c_ndn ) ) {
911                                 authcDN = slap_empty_bv;
912
913                         } else {
914                                 authcDN = op->o_conn->c_ndn;
915                         }       
916                         rs->sr_err = slap_sasl_matches( op, li->idassert_authz,
917                                         &authcDN, &authcDN );
918                         if ( rs->sr_err != LDAP_SUCCESS ) {
919                                 if ( li->idassert_flags & LDAP_BACK_AUTH_PRESCRIPTIVE ) {
920                                         send_ldap_result( op, rs );
921                                         lc->lc_bound = 0;
922
923                                 } else {
924                                         rs->sr_err = LDAP_SUCCESS;
925                                         binddn = slap_empty_bv;
926                                         bindcred = slap_empty_bv;
927                                         break;
928                                 }
929
930                                 goto done;
931                         }
932                 }
933
934                 binddn = li->idassert_authcDN;
935                 bindcred = li->idassert_passwd;
936                 dobind = 1;
937                 break;
938         }
939
940         if ( dobind && li->idassert_authmethod == LDAP_AUTH_SASL ) {
941 #ifdef HAVE_CYRUS_SASL
942                 void            *defaults = NULL;
943                 struct berval   authzID = BER_BVNULL;
944                 int             freeauthz = 0;
945
946                 /* if SASL supports native authz, prepare for it */
947                 if ( ( !op->o_do_not_cache || !op->o_is_auth_check ) &&
948                                 ( li->idassert_flags & LDAP_BACK_AUTH_NATIVE_AUTHZ ) )
949                 {
950                         switch ( li->idassert_mode ) {
951                         case LDAP_BACK_IDASSERT_OTHERID:
952                         case LDAP_BACK_IDASSERT_OTHERDN:
953                                 authzID = li->idassert_authzID;
954                                 break;
955
956                         case LDAP_BACK_IDASSERT_ANONYMOUS:
957                                 BER_BVSTR( &authzID, "dn:" );
958                                 break;
959
960                         case LDAP_BACK_IDASSERT_SELF:
961                                 if ( BER_BVISNULL( &op->o_conn->c_ndn ) ) {
962                                         /* connection is not authc'd, so don't idassert */
963                                         BER_BVSTR( &authzID, "dn:" );
964                                         break;
965                                 }
966                                 authzID.bv_len = STRLENOF( "dn:" ) + op->o_conn->c_ndn.bv_len;
967                                 authzID.bv_val = slap_sl_malloc( authzID.bv_len + 1, op->o_tmpmemctx );
968                                 AC_MEMCPY( authzID.bv_val, "dn:", STRLENOF( "dn:" ) );
969                                 AC_MEMCPY( authzID.bv_val + STRLENOF( "dn:" ),
970                                                 op->o_conn->c_ndn.bv_val, op->o_conn->c_ndn.bv_len + 1 );
971                                 freeauthz = 1;
972                                 break;
973
974                         default:
975                                 break;
976                         }
977                 }
978
979 #if 0   /* will deal with this later... */
980                 if ( sasl_secprops != NULL ) {
981                         rs->sr_err = ldap_set_option( lc->lc_ld, LDAP_OPT_X_SASL_SECPROPS,
982                                 (void *) sasl_secprops );
983
984                         if ( rs->sr_err != LDAP_OPT_SUCCESS ) {
985                                 send_ldap_result( op, rs );
986                                 lc->lc_bound = 0;
987                                 goto done;
988                         }
989                 }
990 #endif
991
992                 defaults = lutil_sasl_defaults( lc->lc_ld,
993                                 li->idassert_sasl_mech.bv_val,
994                                 li->idassert_sasl_realm.bv_val,
995                                 li->idassert_authcID.bv_val,
996                                 li->idassert_passwd.bv_val,
997                                 authzID.bv_val );
998
999                 rs->sr_err = ldap_sasl_interactive_bind_s( lc->lc_ld, binddn.bv_val,
1000                                 li->idassert_sasl_mech.bv_val, NULL, NULL,
1001                                 LDAP_SASL_QUIET, lutil_sasl_interact,
1002                                 defaults );
1003
1004                 lutil_sasl_freedefs( defaults );
1005                 if ( freeauthz ) {
1006                         slap_sl_free( authzID.bv_val, op->o_tmpmemctx );
1007                 }
1008
1009                 rs->sr_err = slap_map_api2result( rs );
1010                 if ( rs->sr_err != LDAP_SUCCESS ) {
1011                         lc->lc_bound = 0;
1012                         send_ldap_result( op, rs );
1013
1014                 } else {
1015                         lc->lc_bound = 1;
1016                 }
1017                 goto done;
1018 #endif /* HAVE_CYRUS_SASL */
1019         }
1020
1021         switch ( li->idassert_authmethod ) {
1022         case LDAP_AUTH_SIMPLE:
1023                 rs->sr_err = ldap_sasl_bind( lc->lc_ld,
1024                                 binddn.bv_val, LDAP_SASL_SIMPLE,
1025                                 &bindcred, NULL, NULL, &msgid );
1026                 break;
1027
1028         case LDAP_AUTH_NONE:
1029                 lc->lc_bound = 1;
1030                 goto done;
1031
1032         default:
1033                 /* unsupported! */
1034                 lc->lc_bound = 0;
1035                 rs->sr_err = LDAP_AUTH_METHOD_NOT_SUPPORTED;
1036                 send_ldap_result( op, rs );
1037                 goto done;
1038         }
1039
1040         rc = ldap_back_op_result( lc, op, rs, msgid, LDAP_BACK_SENDERR );
1041         if ( rc == LDAP_SUCCESS ) {
1042                 lc->lc_bound = 1;
1043         }
1044 done:;
1045         return lc->lc_bound;
1046 }
1047
1048 /*
1049  * ldap_back_proxy_authz_ctrl() prepends a proxyAuthz control
1050  * to existing server-side controls if required; if not,
1051  * the existing server-side controls are placed in *pctrls.
1052  * The caller, after using the controls in client API 
1053  * operations, if ( *pctrls != op->o_ctrls ), should
1054  * free( (*pctrls)[ 0 ] ) and free( *pctrls ).
1055  * The function returns success if the control could
1056  * be added if required, or if it did nothing; in the future,
1057  * it might return some error if it failed.
1058  * 
1059  * if no bind took place yet, but the connection is bound
1060  * and the "proxyauthzdn" is set, then bind as "proxyauthzdn" 
1061  * and explicitly add proxyAuthz the control to every operation
1062  * with the dn bound to the connection as control value.
1063  *
1064  * If no server-side controls are defined for the operation,
1065  * simply add the proxyAuthz control; otherwise, if the
1066  * proxyAuthz control is not already set, add it as
1067  * the first one
1068  *
1069  * FIXME: is controls order significant for security?
1070  * ANSWER: controls ordering and interoperability
1071  * must be indicated by the specs of each control; if none
1072  * is specified, the order is irrelevant.
1073  */
1074 int
1075 ldap_back_proxy_authz_ctrl(
1076                 struct ldapconn *lc,
1077                 Operation       *op,
1078                 SlapReply       *rs,
1079                 LDAPControl     ***pctrls )
1080 {
1081         struct ldapinfo *li = (struct ldapinfo *) op->o_bd->be_private;
1082         LDAPControl     **ctrls = NULL;
1083         int             i = 0,
1084                         mode;
1085         struct berval   assertedID;
1086
1087         *pctrls = NULL;
1088
1089         rs->sr_err = LDAP_SUCCESS;
1090
1091         /* FIXME: SASL/EXTERNAL over ldapi:// doesn't honor the authcID,
1092          * but if it is not set this test fails.  We need a different
1093          * means to detect if idassert is enabled */
1094         if ( ( BER_BVISNULL( &li->idassert_authcID ) || BER_BVISEMPTY( &li->idassert_authcID ) )
1095                         && ( BER_BVISNULL( &li->idassert_authcDN ) || BER_BVISEMPTY( &li->idassert_authcDN ) ) )
1096         {
1097                 goto done;
1098         }
1099
1100         if ( !op->o_conn || op->o_do_not_cache || be_isroot( op ) ) {
1101                 goto done;
1102         }
1103
1104         if ( li->idassert_mode == LDAP_BACK_IDASSERT_LEGACY ) {
1105                 if ( op->o_proxy_authz ) {
1106                         /*
1107                          * FIXME: we do not want to perform proxyAuthz
1108                          * on behalf of the client, because this would
1109                          * be performed with "proxyauthzdn" privileges.
1110                          *
1111                          * This might actually be too strict, since
1112                          * the "proxyauthzdn" authzTo, and each entry's
1113                          * authzFrom attributes may be crafted
1114                          * to avoid unwanted proxyAuthz to take place.
1115                          */
1116 #if 0
1117                         rs->sr_err = LDAP_UNWILLING_TO_PERFORM;
1118                         rs->sr_text = "proxyAuthz not allowed within namingContext";
1119 #endif
1120                         goto done;
1121                 }
1122
1123                 if ( !BER_BVISNULL( &lc->lc_bound_ndn ) ) {
1124                         goto done;
1125                 }
1126
1127                 if ( BER_BVISNULL( &op->o_conn->c_ndn ) ) {
1128                         goto done;
1129                 }
1130
1131                 if ( BER_BVISNULL( &li->idassert_authcDN ) ) {
1132                         goto done;
1133                 }
1134
1135         } else if ( li->idassert_authmethod == LDAP_AUTH_SASL ) {
1136                 if ( ( li->idassert_flags & LDAP_BACK_AUTH_NATIVE_AUTHZ )
1137                                 /* && ( !BER_BVISNULL( &op->o_conn->c_ndn ) || lc->lc_bound ) */ )
1138                 {
1139                         /* already asserted in SASL via native authz */
1140                         /* NOTE: the test on lc->lc_bound is used to trap
1141                          * native authorization of anonymous users,
1142                          * since in that case op->o_conn->c_ndn is NULL */
1143                         goto done;
1144                 }
1145
1146         } else if ( li->idassert_authz && !be_isroot( op ) ) {
1147                 int             rc;
1148                 struct berval authcDN;
1149
1150                 if ( BER_BVISNULL( &op->o_conn->c_ndn ) ) {
1151                         authcDN = slap_empty_bv;
1152                 } else {
1153                         authcDN = op->o_conn->c_ndn;
1154                 }
1155                 rc = slap_sasl_matches( op, li->idassert_authz,
1156                                 &authcDN, & authcDN );
1157                 if ( rc != LDAP_SUCCESS ) {
1158                         if ( li->idassert_flags & LDAP_BACK_AUTH_PRESCRIPTIVE )
1159                         {
1160                                 /* op->o_conn->c_ndn is not authorized
1161                                  * to use idassert */
1162                                 return rc;
1163                         }
1164                         return rs->sr_err;
1165                 }
1166         }
1167
1168         if ( op->o_proxy_authz ) {
1169                 /*
1170                  * FIXME: we can:
1171                  * 1) ignore the already set proxyAuthz control
1172                  * 2) leave it in place, and don't set ours
1173                  * 3) add both
1174                  * 4) reject the operation
1175                  *
1176                  * option (4) is very drastic
1177                  * option (3) will make the remote server reject
1178                  * the operation, thus being equivalent to (4)
1179                  * option (2) will likely break the idassert
1180                  * assumptions, so we cannot accept it;
1181                  * option (1) means that we are contradicting
1182                  * the client's reques.
1183                  *
1184                  * I think (4) is the only correct choice.
1185                  */
1186                 rs->sr_err = LDAP_UNWILLING_TO_PERFORM;
1187                 rs->sr_text = "proxyAuthz not allowed within namingContext";
1188         }
1189
1190         if ( op->o_do_not_cache && op->o_is_auth_check ) {
1191                 mode = LDAP_BACK_IDASSERT_NOASSERT;
1192
1193         } else {
1194                 mode = li->idassert_mode;
1195         }
1196
1197         switch ( mode ) {
1198         case LDAP_BACK_IDASSERT_LEGACY:
1199         case LDAP_BACK_IDASSERT_SELF:
1200                 /* original behavior:
1201                  * assert the client's identity */
1202                 if ( BER_BVISNULL( &op->o_conn->c_ndn ) ) {
1203                         assertedID = slap_empty_bv;
1204                 } else {
1205                         assertedID = op->o_conn->c_ndn;
1206                 }
1207                 break;
1208
1209         case LDAP_BACK_IDASSERT_ANONYMOUS:
1210                 /* assert "anonymous" */
1211                 assertedID = slap_empty_bv;
1212                 break;
1213
1214         case LDAP_BACK_IDASSERT_NOASSERT:
1215                 /* don't assert; bind as proxyauthzdn */
1216                 goto done;
1217
1218         case LDAP_BACK_IDASSERT_OTHERID:
1219         case LDAP_BACK_IDASSERT_OTHERDN:
1220                 /* assert idassert DN */
1221                 assertedID = li->idassert_authzID;
1222                 break;
1223
1224         default:
1225                 assert( 0 );
1226         }
1227
1228         if ( BER_BVISNULL( &assertedID ) ) {
1229                 assertedID = slap_empty_bv;
1230         }
1231
1232         if ( op->o_ctrls ) {
1233                 for ( i = 0; op->o_ctrls[ i ]; i++ )
1234                         /* just count ctrls */ ;
1235         }
1236
1237         ctrls = ch_malloc( sizeof( LDAPControl * ) * (i + 2) );
1238         ctrls[ 0 ] = ch_malloc( sizeof( LDAPControl ) );
1239         
1240         ctrls[ 0 ]->ldctl_oid = LDAP_CONTROL_PROXY_AUTHZ;
1241         ctrls[ 0 ]->ldctl_iscritical = 1;
1242
1243         switch ( li->idassert_mode ) {
1244         /* already in u:ID or dn:DN form */
1245         case LDAP_BACK_IDASSERT_OTHERID:
1246         case LDAP_BACK_IDASSERT_OTHERDN:
1247                 ber_dupbv( &ctrls[ 0 ]->ldctl_value, &assertedID );
1248                 break;
1249
1250         /* needs the dn: prefix */
1251         default:
1252                 ctrls[ 0 ]->ldctl_value.bv_len = assertedID.bv_len + STRLENOF( "dn:" );
1253                 ctrls[ 0 ]->ldctl_value.bv_val = ch_malloc( ctrls[ 0 ]->ldctl_value.bv_len + 1 );
1254                 AC_MEMCPY( ctrls[ 0 ]->ldctl_value.bv_val, "dn:", STRLENOF( "dn:" ) );
1255                 AC_MEMCPY( &ctrls[ 0 ]->ldctl_value.bv_val[ STRLENOF( "dn:" ) ],
1256                                 assertedID.bv_val, assertedID.bv_len + 1 );
1257                 break;
1258         }
1259
1260         if ( op->o_ctrls ) {
1261                 for ( i = 0; op->o_ctrls[ i ]; i++ ) {
1262                         ctrls[ i + 1 ] = op->o_ctrls[ i ];
1263                 }
1264         }
1265         ctrls[ i + 1 ] = NULL;
1266
1267 done:;
1268         if ( ctrls == NULL ) {
1269                 ctrls = op->o_ctrls;
1270         }
1271
1272         *pctrls = ctrls;
1273         
1274         return rs->sr_err;
1275 }
1276
1277 int
1278 ldap_back_proxy_authz_ctrl_free( Operation *op, LDAPControl ***pctrls )
1279 {
1280         LDAPControl     **ctrls = *pctrls;
1281
1282         /* we assume that the first control is the proxyAuthz
1283          * added by back-ldap, so it's the only one we explicitly 
1284          * free */
1285         if ( ctrls && ctrls != op->o_ctrls ) {
1286                 assert( ctrls[ 0 ] != NULL );
1287
1288                 if ( !BER_BVISNULL( &ctrls[ 0 ]->ldctl_value ) ) {
1289                         free( ctrls[ 0 ]->ldctl_value.bv_val );
1290                 }
1291
1292                 free( ctrls[ 0 ] );
1293                 free( ctrls );
1294         } 
1295
1296         *pctrls = NULL;
1297
1298         return 0;
1299 }