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