[Summary view] [Print] [Text view]

   1  =head1 NAME
   2  
   3  Net::LDAP - Lightweight Directory Access Protocol
   4  
   5  =head1 SYNOPSIS
   6  
   7   use Net::LDAP;
   8  
   9   $ldap = Net::LDAP->new( 'ldap.bigfoot.com' ) or die "$@";
  10  
  11   $mesg = $ldap->bind ;    # an anonymous bind
  12  
  13   $mesg = $ldap->search( # perform a search
  14                          base   => "c=US",
  15                          filter => "(&(sn=Barr) (o=Texas Instruments))"
  16                        );
  17  
  18   $mesg->code && die $mesg->error;
  19  
  20   foreach $entry ($mesg->entries) { $entry->dump; }
  21  
  22   $mesg = $ldap->unbind;   # take down session
  23  
  24  
  25   $ldap = Net::LDAP->new( 'ldap.umich.edu' );
  26  
  27   # bind to a directory with dn and password
  28   $mesg = $ldap->bind( 'cn=root, o=University of Michigan, c=us',
  29                        password => 'secret'
  30                      );
  31  
  32   $result = $ldap->add( 'cn=Barbara Jensen, o=University of Michigan, c=US',
  33                         attr => [
  34                           'cn'   => ['Barbara Jensen', 'Barbs Jensen'],
  35                       'sn'   => 'Jensen',
  36                       'mail' => 'b.jensen@umich.edu',
  37                       'objectclass' => ['top', 'person',
  38                                             'organizationalPerson',
  39                                             'inetOrgPerson' ],
  40                         ]
  41                       );
  42  
  43   $result->code && warn "failed to add entry: ", $result->error ;
  44   $mesg = $ldap->unbind;  # take down session
  45  
  46  =head1 DESCRIPTION
  47  
  48  B<Net::LDAP> is a collection of modules that implements a LDAP
  49  services API for Perl programs. The module may be used to search
  50  directories or perform maintenance functions such as adding, deleting
  51  or modifying entries.
  52  
  53  This document assumes that the reader has some knowledge of the LDAP
  54  protocol.
  55  
  56  =head1 CONSTRUCTOR
  57  
  58  =over 4
  59  
  60  =item new ( HOST, OPTIONS )
  61  
  62  Creates a new B<Net::LDAP> object and opens a connection to the named host.
  63  
  64  C<HOST> may be a host name or an IP number. TCP port may be specified
  65  after the host name followed by a colon (such as localhost:10389). The
  66  default TCP port for LDAP is 389.
  67  
  68  You can also specify a URI, such as 'ldaps://127.0.0.1:666' or
  69  'ldapi://%2fvar%2flib%2fldap_sock'. Note that '%2f's in the LDAPI
  70  socket path will be translated into '/'. This is to support LDAP query
  71  options like base, search etc. although the query part of the URI will
  72  be ignored in this context. If port was not specified in the URI, the
  73  default is either 389 or 636 for 'LDAP' and 'LDAPS' schemes
  74  respectively.
  75  
  76  C<HOST> may also be a reference to an array of hosts, host-port pairs
  77  or URIs to try. Each will be tried in order until a connection is
  78  made. Only when all have failed will the result of C<undef> be
  79  returned.
  80  
  81  =over 4
  82  
  83  =item port =E<gt> N
  84  
  85  Port to connect to on the remote server. May be overridden by C<HOST>.
  86  
  87  =item scheme =E<gt> 'ldap' | 'ldaps' | 'ldapi'
  88  
  89  Connection scheme to use when not using an URI as C<HOST>.
  90  (Default: ldap)
  91  
  92  =item timeout =E<gt> N
  93  
  94  Timeout passed to L<IO::Socket> when connecting the remote server.
  95  (Default: 120)
  96  
  97  =item multihomed =E<gt> N
  98  
  99  Will be passed to L<IO::Socket> as the C<MultiHomed> parameter
 100  when connecting to the remote server
 101  
 102  =item localaddr =E<gt> HOST
 103  
 104  Will be passed to L<IO::Socket> as the C<LocalAddr> parameter, which
 105  sets the client's IP address (as opposed to the server's IP address.)
 106  
 107  =item debug =E<gt> N
 108  
 109  Set the debug level. See the L<debug|/debug> method for details.
 110  
 111  =item async =E<gt> 1
 112  
 113  Perform all operations asynchronously.
 114  
 115  =item onerror =E<gt> 'die' | 'warn' | undef | sub { ... }
 116  
 117  In synchronous mode, change what happens when an error is detected.
 118  
 119  =over 4
 120  
 121  =item 'die'
 122  
 123  Net::LDAP will croak whenever an error is detected.
 124  
 125  =item 'warn'
 126  
 127  Net::LDAP will warn whenever an error is detected.
 128  
 129  =item undef
 130  
 131  Net::LDAP will warn whenever an error is detected and C<-w> is in
 132  effect. The method that was called will return C<undef>.
 133  
 134  =item sub { ... }
 135  
 136  The given sub will be called in a scalar context with a single
 137  argument, the result message. The value returned will be the return
 138  value for the method that was called.
 139  
 140  =back
 141  
 142  =item version =E<gt> N
 143  
 144  Set the protocol version being used (default is LDAPv3). This is
 145  useful if you want to talk to an old server and therefore have to use
 146  LDAPv2.
 147  
 148  =item raw =E<gt> REGEX
 149  
 150  Use REGEX to denote the names of attributes that are to be considered
 151  binary in search results.
 152  
 153  When running on Perl 5.8 and this option is given Net::LDAP converts all
 154  values of attributes not matching this REGEX into Perl UTF-8 strings
 155  so that the regular Perl operators (pattern matching, ...) can operate
 156  as one expects even on strings with international characters.
 157  
 158  If this option is not given or the version of Perl Net::LDAP is running
 159  on is too old strings are encoded the same as in earlier versions of
 160  perl-ldap.
 161  
 162  Example: raw =E<gt> qr/(?i:^jpegPhoto|;binary)/
 163  
 164  =item inet6 =E<gt> N
 165  
 166  Try to connect to the server using IPv6 if C<HOST> resolves to an 
 167  IPv6 target address.
 168  If it resolves to an IPv4 address, the connection is tried using IPv4,
 169  the same way as if this option was not given.
 170  
 171  Please note that IPv6 support is considered experimental in
 172  IO::Socket::SSL, which is used of SSL/TLS support, and there are a few
 173  issues to take care of. See L<IO::Socket::SSL/IPv6> for details.
 174  
 175  =back
 176  
 177  B<Example>
 178  
 179    $ldap = Net::LDAP->new( 'remote.host', async => 1 );
 180  
 181  LDAPS connections have some extra valid options, see the
 182  L<start_tls|/start_tls> method for details. Note the default value for
 183  'sslversion' for LDAPS is 'sslv2/3', and the default port for LDAPS
 184  is 636.
 185  
 186  For LDAPI connections, HOST is actually the location of a UNIX domain
 187  socket to connect to. The default location is '/var/run/ldapi'.
 188  
 189  =back
 190  
 191  =head1 METHODS
 192  
 193  Each of the following methods take as arguments some number of fixed
 194  parameters followed by options, these options are passed in a named
 195  fashion, for example
 196  
 197    $mesg = $ldap->bind( "cn=me,o=example", password => "mypasswd");
 198  
 199  The return value from these methods is an object derived from the
 200  L<Net::LDAP::Message> class. The methods of this class allow
 201  you to examine the status of the request.
 202  
 203  
 204  =over 4
 205  
 206  =item abandon ( ID, OPTIONS )
 207  
 208  Abandon a previously issued request. C<ID> may be a number or an
 209  object which is a sub-class of L<Net::LDAP::Message>, returned from a
 210  previous method call.
 211  
 212  =over 4
 213  
 214  =item control =E<gt> CONTROL
 215  
 216  =item control =E<gt> [ CONTROL, ... ]
 217  
 218  See L</CONTROLS> below
 219  
 220  =item callback =E<gt> CALLBACK
 221  
 222  See L</CALLBACKS> below
 223  
 224  =back
 225  
 226  B<Example>
 227  
 228    $res = $ldap->search( @search_args );
 229  
 230    $mesg = $ldap->abandon( $res ); # This could be written as $res->abandon
 231  
 232  
 233  =item add ( DN, OPTIONS )
 234  
 235  Add a new entry to the directory. C<DN> can be either a
 236  L<Net::LDAP::Entry> object or a string.
 237  
 238  =over 4
 239  
 240  =item attrs =E<gt> [ ATTR =E<gt> VALUE, ... ]
 241  
 242  C<VALUE> should be a string if only a single value is wanted, or a
 243  reference to an array of strings if multiple values are wanted.
 244  
 245  This argument is not used if C<DN> is a L<Net::LDAP::Entry> object.
 246  
 247  =item control =E<gt> CONTROL
 248  
 249  =item control =E<gt> [ CONTROL, ... ]
 250  
 251  See L</CONTROLS> below
 252  
 253  =item callback =E<gt> CALLBACK
 254  
 255  See L</CALLBACKS> below
 256  
 257  =back
 258  
 259  B<Example>
 260  
 261    # $entry is an object of class Net::LDAP::Entry
 262    $mesg = $ldap->add( $entry );
 263  
 264    $mesg = $ldap->add( $dn,
 265                        attrs => [
 266                          name  => 'Graham Barr',
 267                          attr  => 'value1',
 268                          attr  => 'value2',
 269                          multi => [qw(value1 value2)]
 270                        ]
 271                      );
 272  
 273  =item bind ( DN, OPTIONS )
 274  
 275  Bind (log in) to the server. C<DN> is the DN to bind with. An
 276  anonymous bind may be done by calling bind without any arguments.
 277  
 278  =over 4
 279  
 280  =item control =E<gt> CONTROL
 281  
 282  =item control =E<gt> [ CONTROL, ... ]
 283  
 284  See L</CONTROLS> below
 285  
 286  =item callback =E<gt> CALLBACK
 287  
 288  See L</CALLBACKS> below
 289  
 290  =item noauth | anonymous =E<gt> 1
 291  
 292  Bind without any password. The value passed with this option is ignored.
 293  
 294  =item password =E<gt> PASSWORD
 295  
 296  Bind with the given password.
 297  
 298  =item sasl =E<gt> SASLOBJ
 299  
 300  Bind using a SASL mechanism. The argument given should be a sub-class
 301  of L<Authen::SASL>.
 302  
 303  =back
 304  
 305  B<Example>
 306  
 307    $mesg = $ldap->bind; # Anonymous bind
 308  
 309    $mesg = $ldap->bind( $dn, password => $password );
 310  
 311    # $sasl is an object of class Authen::SASL
 312    $mesg = $ldap->bind( $dn, sasl => $sasl, version => 3 );
 313  
 314  
 315  =item compare ( DN, OPTIONS )
 316  
 317  Compare values in an attribute in the entry given by C<DN> on the
 318  server. C<DN> may be a string or a L<Net::LDAP::Entry> object.
 319  
 320  =over 4
 321  
 322  =item attr =E<gt> ATTR
 323  
 324  The name of the attribute to compare.
 325  
 326  =item value =E<gt> VALUE
 327  
 328  The value to compare with.
 329  
 330  =item control =E<gt> CONTROL
 331  
 332  =item control =E<gt> [ CONTROL, ... ]
 333  
 334  See L</CONTROLS> below.
 335  
 336  =item callback =E<gt> CALLBACK
 337  
 338  See L</CALLBACKS> below.
 339  
 340  =back
 341  
 342  B<Example>
 343  
 344    $mesg = $ldap->compare( $dn,
 345                            attr  => 'cn',
 346                            value => 'Graham Barr'
 347                          );
 348  
 349  =item delete ( DN, OPTIONS )
 350  
 351  Delete the entry given by C<DN> from the server. C<DN> may be a string
 352  or a L<Net::LDAP::Entry> object.
 353  
 354  =over 4
 355  
 356  =item control =E<gt> CONTROL
 357  
 358  =item control =E<gt> [ CONTROL, ... ]
 359  
 360  See L</CONTROLS> below.
 361  
 362  =item callback =E<gt> CALLBACK
 363  
 364  See L</CALLBACKS> below.
 365  
 366  =back
 367  
 368  B<Example>
 369  
 370   $mesg = $ldap->delete( $dn );
 371  
 372  =item moddn ( DN, OPTIONS )
 373  
 374  Rename the entry given by C<DN> on the server. C<DN> may be a string
 375  or a L<Net::LDAP::Entry> object.
 376  
 377  =over 4
 378  
 379  =item newrdn =E<gt> RDN
 380  
 381  This value should be a new RDN to assign to C<DN>.
 382  
 383  =item deleteoldrdn =E<gt> 1
 384  
 385  This option should be passwd if the existing RDN is to be deleted.
 386  
 387  =item newsuperior =E<gt> NEWDN
 388  
 389  If given this value should be the DN of the new superior for C<DN>.
 390  
 391  =item control =E<gt> CONTROL
 392  
 393  =item control =E<gt> [ CONTROL, ... ]
 394  
 395  See L</CONTROLS> below.
 396  
 397  =item callback =E<gt> CALLBACK
 398  
 399  See L</CALLBACKS> below.
 400  
 401  =back
 402  
 403  B<Example>
 404  
 405   $mesg = $ldap->moddn( $dn, newrdn => 'cn=Graham Barr' );
 406  
 407  =item modify ( DN, OPTIONS )
 408  
 409  Modify the contents of the entry given by C<DN> on the server. C<DN>
 410  may be a string or a L<Net::LDAP::Entry> object.
 411  
 412  =over 4
 413  
 414  =item add =E<gt> { ATTR =E<gt> VALUE, ... }
 415  
 416  Add more attributes or values to the entry. C<VALUE> should be a
 417  string if only a single value is wanted in the attribute, or a
 418  reference to an array of strings if multiple values are wanted.
 419  
 420    $mesg = $ldap->modify( $dn,
 421      add => {
 422        description => 'List of members',    # Add description attribute
 423        member      => [
 424          'cn=member1,ou=people,dc=example,dc=com',    # Add to attribute
 425          'cn=member2,ou=people,dc=example,dc=com',
 426        ]
 427      }
 428    );
 429  
 430  =item delete =E<gt> [ ATTR, ... ]
 431  
 432  Delete complete attributes from the entry.
 433  
 434    $mesg = $ldap->modify( $dn,
 435      delete => ['member','description'] # Delete attributes
 436    );
 437  
 438  =item delete =E<gt> { ATTR =E<gt> VALUE, ... }
 439  
 440  Delete individual values from an attribute. C<VALUE> should be a
 441  string if only a single value is being deleted from the attribute, or
 442  a reference to an array of strings if multiple values are being
 443  deleted.
 444  
 445  If C<VALUE> is a reference to an empty array or all existing values
 446  of the attribute are being deleted, then the attribute will be
 447  deleted from the entry.
 448  
 449    $mesg = $ldap->modify( $dn,
 450      delete => {
 451        description => 'List of members',
 452        member      => [
 453          'cn=member1,ou=people,dc=example,dc=com',    # Remove members
 454          'cn=member2,ou=people,dc=example,dc=com',
 455        ],
 456        seeAlso => [],   # Remove attribute
 457      }
 458    );
 459  
 460  =item replace =E<gt> { ATTR =E<gt> VALUE, ... }
 461  
 462  Replace any existing values in each given attribute with
 463  C<VALUE>. C<VALUE> should be a string if only a single value is wanted
 464  in the attribute, or a reference to an array of strings if multiple
 465  values are wanted. A reference to an empty array will remove the
 466  entire attribute. If the attribute does not already exist in the
 467  entry, it will be created.
 468  
 469    $mesg = $ldap->modify( $dn,
 470      replace => {
 471        description => 'New List of members', # Change the description
 472        member      => [ # Replace whole list with these
 473          'cn=member1,ou=people,dc=example,dc=com',   
 474          'cn=member2,ou=people,dc=example,dc=com',
 475        ],
 476        seeAlso => [],   # Remove attribute
 477      }
 478    );
 479  
 480  =item increment =E<gt> { ATTR =E<gt> VALUE, ... }
 481  
 482  Atomically increment the existing value in each given attribute by the
 483  provided C<VALUE>. The attributes need to have integer syntax, or be
 484  otherwise "incrementable". Note this will only work if the server
 485  advertizes support for LDAP_FEATURE_MODIFY_INCREMENT. Use 
 486  L<Net::LDAP::RootDSE/supported_feature> to check this.
 487  
 488    $mesg = $ldap->modify( $dn,
 489      increment => {
 490        uidNumber => 1 # increment uidNumber by 1
 491      }
 492    );
 493  
 494  =item changes =E<gt> [ OP =E<gt> [ ATTR =E<gt> VALUE ], ... ]
 495  
 496  This is an alternative to B<add>, B<delete>, B<replace> and B<increment>
 497  where the whole operation can be given in a single argument. C<OP>
 498  should be B<add>, B<delete>, B<replace> or B<increment>. C<VALUE> should
 499  be either a string or a reference to an array of strings, as before.
 500  
 501  Use this form if you want to control the order in which the operations
 502  will be performed.
 503  
 504    $mesg = $ldap->modify( $dn,
 505      changes => [
 506        add => [
 507          description => 'A description',
 508          member      => $newMember,
 509        ],
 510        delete => [
 511          seeAlso => [],
 512        ],
 513        add => [
 514          anotherAttribute => $value,
 515        ],
 516      ]
 517    );
 518  
 519  =item control =E<gt> CONTROL
 520  
 521  =item control =E<gt> [ CONTROL, ... ]
 522  
 523  See L</CONTROLS> below.
 524  
 525  =item callback =E<gt> CALLBACK
 526  
 527  See L</CALLBACKS> below.
 528  
 529  =back
 530  
 531  B<Example>
 532  
 533   $mesg = $ldap->modify( $dn, add => { sn => 'Barr' } );
 534  
 535   $mesg = $ldap->modify( $dn, delete => [qw(faxNumber)] );
 536  
 537   $mesg = $ldap->modify( $dn, delete => { 'telephoneNumber' => '911' } );
 538  
 539   $mesg = $ldap->modify( $dn, replace => { 'mail' => 'gbarr@pobox.com' } );
 540  
 541   $mesg = $ldap->modify( $dn,
 542                          changes => [
 543                              # add sn=Barr
 544                            add     => [ sn => 'Barr' ],
 545                              # delete all fax numbers
 546                            delete  => [ faxNumber => []],
 547                              # delete phone number 911
 548                            delete  => [ telephoneNumber => ['911']],
 549                              # change email address
 550                            replace => [ mail => 'gbarr@pobox.com']
 551                          ]
 552                        );
 553  
 554  =item search ( OPTIONS )
 555  
 556  Search the directory using a given filter.  This can be used to read
 557  attributes from a single entry, from entries immediately below a
 558  particular entry, or a whole subtree of entries.
 559  
 560  The result is an object of class L<Net::LDAP::Search>.
 561  
 562  =over 4
 563  
 564  =item base =E<gt> DN
 565  
 566  The DN that is the base object entry relative to which the search is
 567  to be performed.
 568  
 569  =item scope =E<gt> 'base' | 'one' | 'sub'
 570  
 571  By default the search is performed on the whole tree below
 572  the specified base object. This maybe changed by specifying a C<scope>
 573  parameter with one of the following values:
 574  
 575  =over 4
 576  
 577  =item base
 578  
 579  Search only the base object.
 580  
 581  =item one
 582  
 583  Search the entries immediately below the base object.
 584  
 585  =item sub
 586  
 587  Search the whole tree below (and including) the base object. This is
 588  the default.
 589  
 590  =back
 591  
 592  =item deref =E<gt> 'never' | 'search' | 'find' | 'always'
 593  
 594  By default aliases are dereferenced to locate the base object for the
 595  search, but not when searching subordinates of the base object. This
 596  may be changed by specifying a C<deref> parameter with one of the
 597  following values:
 598  
 599  =over 4
 600  
 601  =item never
 602  
 603  Do not dereference aliases in searching or in locating the base object
 604  of the search.
 605  
 606  =item search
 607  
 608  Dereference aliases in subordinates of the base object in searching,
 609  but not in locating the base object of the search.
 610  
 611  =item find
 612  
 613  Dereference aliases in locating the base object of the search, but not
 614  when searching subordinates of the base object. This is the default.
 615  
 616  =item always
 617  
 618  Dereference aliases both in searching and in locating the base object
 619  of the search.
 620  
 621  =back
 622  
 623  =item sizelimit =E<gt> N
 624  
 625  A sizelimit that restricts the maximum number of entries to be returned
 626  as a result of the search. A value of 0, and the default, means that
 627  no restriction is requested.  Servers may enforce a maximum number of
 628  entries to return.
 629  
 630  =item timelimit =E<gt> N
 631  
 632  A timelimit that restricts the maximum time (in seconds) allowed for a
 633  search. A value of 0 (the default), means that no timelimit will be
 634  requested.
 635  
 636  =item typesonly =E<gt> 1
 637  
 638  Only attribute types (no values) should be returned. Normally
 639  attribute types and values are returned.
 640  
 641  =item filter =E<gt> FILTER
 642  
 643  A filter that defines the conditions an entry in the directory must meet
 644  in order for it to be returned by the search. This may be a string or a
 645  L<Net::LDAP::Filter> object. Values inside filters may need to be escaped
 646  to avoid security problems; see L<Net::LDAP::Filter> for a definition of
 647  the filter format, including the escaping rules.
 648  
 649  =item attrs =E<gt> [ ATTR, ... ]
 650  
 651  A list of attributes to be returned for each entry that matches the
 652  search filter.
 653  
 654  If not specified, then the server will return the attributes that are
 655  specified as accessible by default given your bind credentials.
 656  
 657  Certain additional attributes such as "createTimestamp" and other
 658  operational attributes may also be available for the asking:
 659  
 660    $mesg = $ldap->search( ... ,
 661                           attrs => ['createTimestamp']
 662                         );
 663  
 664  To retrieve the default attributes and additional ones, use '*'.
 665  
 666    $mesg = $ldap->search( ... ,
 667                           attrs => ['*', 'createTimestamp']
 668                         );
 669  
 670  To retrieve no attributes (the server only returns the DNs of matching
 671  entries), use '1.1':
 672  
 673    $mesg = $ldap->search( ... ,
 674                           attrs => ['1.1']
 675                         );
 676  
 677  =item control =E<gt> CONTROL
 678  
 679  =item control =E<gt> [ CONTROL, ... ]
 680  
 681  See L</CONTROLS> below.
 682  
 683  =item callback =E<gt> CALLBACK
 684  
 685  See L</CALLBACKS> below.
 686  
 687  =item raw =E<gt> REGEX
 688  
 689  Use REGEX to denote the names of attributes that are to be considered
 690  binary in search results.
 691  
 692  When running on Perl 5.8 and this option is given Net::LDAP converts all
 693  values of attributes not matching this REGEX into Perl UTF-8 strings
 694  so that the regular Perl operators (pattern matching, ...) can operate
 695  as one expects even on strings with international characters.
 696  
 697  If this option is not given or the version of Perl Net::LDAP is running on
 698  is too old strings are encodeed the same as in earlier versions of perl-ldap.
 699  
 700  The value provided here overwrites the value inherited from the constructor.
 701  
 702  Example: raw =E<gt> qr/(?i:^jpegPhoto|;binary)/
 703  
 704  =back
 705  
 706  B<Example>
 707  
 708   $mesg = $ldap->search(
 709                          base   => $base_dn,
 710                          scope  => 'sub',
 711                          filter => '(|(objectclass=rfc822mailgroup)(sn=jones))'
 712                        );
 713  
 714   Net::LDAP::LDIF->new( \*STDOUT,"w" )->write( $mesg->entries );
 715  
 716  =item start_tls ( OPTIONS )
 717  
 718  Calling this method will convert the existing connection to using
 719  Transport Layer Security (TLS), which provides an encrypted
 720  connection. This is I<only> possible if the connection uses LDAPv3,
 721  and requires that the server advertizes support for
 722  LDAP_EXTENSION_START_TLS. Use
 723  L<Net::LDAP::RootDSE/supported_extension> to check this.
 724  
 725  =over 4
 726  
 727  =item verify =E<gt> 'none' | 'optional' | 'require'
 728  
 729  How to verify the server's certificate:
 730  
 731  =over 4
 732  
 733  =item none
 734  
 735  The server may provide a certificate but it will not be checked - this
 736  may mean you are be connected to the wrong server
 737  
 738  =item optional
 739  
 740  Verify only when the server offers a certificate
 741  
 742  =item require
 743  
 744  The server must provide a certificate, and it must be valid.
 745  
 746  =back
 747  
 748  If you set verify to optional or require, you must also set either
 749  cafile or capath. The most secure option is B<require>.
 750  
 751  =item sslversion =E<gt> 'sslv2' | 'sslv3' | 'sslv2/3' | 'tlsv1'
 752  
 753  This defines the version of the SSL/TLS protocol to use. Defaults to
 754  B<'tlsv1'>.
 755  
 756  =item ciphers =E<gt> CIPHERS
 757  
 758  Specify which subset of cipher suites are permissible for this
 759  connection, using the standard OpenSSL string format. The default
 760  value is B<'ALL'>, which permits all ciphers, even those that don't
 761  encrypt.
 762  
 763  =item clientcert =E<gt> '/path/to/cert.pem'
 764  
 765  =item clientkey =E<gt> '/path/to/key.pem'
 766  
 767  =item keydecrypt =E<gt> sub { ... }
 768  
 769  If you want to use the client to offer a certificate to the server for
 770  SSL authentication (which is not the same as for the LDAP Bind
 771  operation) then set clientcert to the user's certificate file, and
 772  clientkey to the user's private key file. These files must be in PEM
 773  format.
 774  
 775  If the private key is encrypted (highly recommended) then keydecrypt
 776  should be a subroutine that returns the decrypting key. For example:
 777  
 778   $ldap = Net::LDAP->new( 'myhost.example.com', version => 3 );
 779   $mesg = $ldap->start_tls(
 780                             verify => 'require',
 781                             clientcert => 'mycert.pem',
 782                             clientkey => 'mykey.pem',
 783                             keydecrypt => sub { 'secret'; },
 784                             capath => '/usr/local/cacerts/'
 785                           );
 786  
 787  =item capath =E<gt> '/path/to/servercerts/'
 788  
 789  =item cafile =E<gt> '/path/to/servercert.pem'
 790  
 791  When verifying the server's certificate, either set capath to the
 792  pathname of the directory containing CA certificates, or set cafile to
 793  the filename containing the certificate of the CA who signed the
 794  server's certificate. These certificates must all be in PEM format.
 795  
 796  The directory in 'capath' must contain certificates named using the
 797  hash value of the certificates' subject names. To generate these
 798  names, use OpenSSL like this in Unix:
 799  
 800      ln -s cacert.pem `openssl x509 -hash -noout < cacert.pem`.0
 801  
 802  (assuming that the certificate of the CA is in cacert.pem.)
 803  
 804  =item checkcrl =E<gt> 1
 805  
 806  If capath has been configured, then it will also be searched for
 807  certificate revocation lists (CRLs) when verifying the server's
 808  certificate.
 809  The CRLs' names must follow the form B<hash>.rB<num> where B<hash>
 810  is the hash over the issuer's DN and B<num> is a number starting with 0.
 811  
 812  See L<IO::Socket::SSL/SSL_check_crl> for further information.
 813  
 814  =back
 815  
 816  =item unbind ( )
 817  
 818  The unbind method does not take any parameters and will unbind you
 819  from the server. Some servers may allow you to re-bind or perform
 820  other operations after unbinding. If you wish to switch to another set
 821  of credentials while continuing to use the same connection, re-binding
 822  with another DN and password, without unbind-ing, will generally work.
 823  
 824  B<Example>
 825  
 826   $mesg = $ldap->unbind;
 827  
 828  =back
 829  
 830  The following methods are for convenience, and do not return
 831  C<Net::LDAP::Message> objects.
 832  
 833  =over 4
 834  
 835  =item async ( VALUE )
 836  
 837  If C<VALUE> is given the async mode will be set. The previous value
 838  will be returned. The value is I<true> if LDAP operations are being
 839  performed asynchronously.
 840  
 841  =item certificate ( )
 842  
 843  Returns an X509_Certificate object containing the server's
 844  certificate. See the IO::Socket::SSL documentation for information
 845  about this class.
 846  
 847  For example, to get the subject name (in a peculiar OpenSSL-specific
 848  format, different from RFC 1779 and RFC 2253) from the server's
 849  certificate, do this:
 850  
 851      print "Subject DN: " . $ldaps->certificate->subject_name . "\n";
 852  
 853  =item cipher ( )
 854  
 855  Returns the cipher mode being used by the connection, in the string
 856  format used by OpenSSL.
 857  
 858  =item debug ( VALUE )
 859  
 860  If C<VALUE> is given the debug bit-value will be set. The previous
 861  value will be returned. Debug output will be sent to C<STDERR>. The
 862  bits of this value are:
 863  
 864   1   Show outgoing packets (using asn_hexdump).
 865   2   Show incoming packets (using asn_hexdump).
 866   4   Show outgoing packets (using asn_dump).
 867   8   Show incoming packets (using asn_dump).
 868  
 869  The default value is 0.
 870  
 871  =item disconnect ( )
 872  
 873  Disconnect from the server
 874  
 875  =item root_dse ( OPTIONS )
 876  
 877  The root_dse method retrieves cached information from the server's
 878  rootDSE.
 879  
 880  =over 4
 881  
 882  =item attrs =E<gt> [ ATTR, ... ]
 883  
 884  A reference to a list of attributes to be returned.
 885  If not specified, then the following attributes will be requested
 886  
 887    subschemaSubentry
 888    namingContexts
 889    altServer
 890    supportedExtension
 891    supportedFeatures
 892    supportedControl
 893    supportedSASLMechanisms
 894    supportedLDAPVersion
 895  
 896  =back
 897  
 898  The result is an object of class L<Net::LDAP::RootDSE>.
 899  
 900  B<Example>
 901  
 902   my $root = $ldap->root_dse;
 903   # get naming Context
 904   $root->get_value( 'namingContext', asref => 1 );
 905   # get supported LDAP versions
 906   $root->supported_version;
 907  
 908  As the root DSE may change in certain circumstances - for instance
 909  when you change the connection using start_tls - you should always use
 910  the root_dse method to return the most up-to-date copy of the root
 911  DSE.
 912  
 913  =item schema ( OPTIONS )
 914  
 915  Read schema information from the server.
 916  
 917  The result is an object of class L<Net::LDAP::Schema>.
 918  Read this documentation for further information about methods that
 919  can be performed with this object.
 920  
 921  =over 4
 922  
 923  =item dn =E<gt> DN
 924  
 925  If a DN is supplied, it will become the base object entry from 
 926  which the search for schema information will be conducted.  If
 927  no DN is supplied the base object entry will be determined from
 928  the rootDSE entry.
 929  
 930  =back
 931  
 932  B<Example>
 933  
 934   my $schema = $ldap->schema;
 935   # get objectClasses
 936   @ocs = $schema->all_objectclasses;
 937   # Get the attributes
 938   @atts = $schema->all_attributes;
 939  
 940  =item socket ( )
 941  
 942  Returns the underlying C<IO::Socket> object being used.
 943  
 944  =item host ( )
 945  
 946  Returns the host to which the connection was established.
 947  For LDAPI connections the socket path is returned.
 948  
 949  =item port ( )
 950  
 951  Returns the the port connected to or C<undef> in case of LDAPI connections.
 952  
 953  =item uri ( )
 954  
 955  Returns the URI connected to.
 956  
 957  As the value returned is that element of the constructor's HOST
 958  argument with which the connection was established this may or
 959  may not be a legal URI.
 960  
 961  =item scheme ( )
 962  
 963  Returns the scheme of the connection. One of I<ldap>, I<ldaps> or I<ldapi>.
 964  
 965  =item sync ( MESG )
 966  
 967  Wait for a given C<MESG> request to be completed by the server. If no
 968  C<MESG> is given, then wait for all outstanding requests to be completed.
 969  
 970  Returns an error code defined in L<Net::LDAP::Constant>.
 971  
 972  =item process ( MESG )
 973  
 974  Process any messages that the server has sent, but do not block. If C<MESG>
 975  is specified then return as soon as C<MESG> has been processed.
 976  
 977  Returns an error code defined in L<Net::LDAP::Constant>.
 978  
 979  =item version ( )
 980  
 981  Returns the version of the LDAP protocol that is being used.
 982  
 983  =back
 984  
 985  =head1 CONTROLS
 986  
 987  Many of the methods described above accept a control option.
 988  This allows the user to pass controls to the server as described
 989  in LDAPv3.
 990  
 991  A control is a reference to a HASH and should contain the three
 992  elements below. If any of the controls are blessed then the
 993  method C<to_asn> will be called which should return a reference
 994  to a HASH containing the three elements described below.
 995  
 996  For most purposes L<Net::LDAP::Control> objects are the easiest
 997  way to generate controls.
 998  
 999  =over 4
1000  
1001  =item type =E<gt> OID
1002  
1003  This element must be present and is the name of the type of control
1004  being requested.
1005  
1006  =item critical =E<gt> FLAG
1007  
1008  critical is optional and should be a boolean value, if it is not specified
1009  then it is assumed to be I<false>.
1010  
1011  =item value =E<gt> VALUE
1012  
1013  If the control being requested requires a value then this element should
1014  hold the value for the server.
1015  
1016  =back
1017  
1018  =head1 CALLBACKS
1019  
1020  Most of the above commands accept a callback option. This option
1021  should be a reference to a subroutine. This subroutine will be called
1022  for each packet received from the server as a response to the request
1023  sent.
1024  
1025  When the subroutine is called the first argument will be the
1026  L<Net::LDAP::Message> object which was returned from the method.
1027  
1028  If the request is a search then multiple packets can be received from
1029  the server. Each entry is received as a separate packet. For each of these
1030  the subroutine will be called with a L<Net::LDAP::Entry> object as the second
1031  argument.
1032  
1033  During a search the server may also send a list of references. When such
1034  a list is received then the subroutine will be called with a
1035  L<Net::LDAP::Reference> object as the second argument.
1036  
1037  =head1 LDAP ERROR CODES
1038  
1039  B<Net::LDAP> also exports constants for the error codes that can be received
1040  from the server, see L<Net::LDAP::Constant>.
1041  
1042  =head1 SEE ALSO
1043  
1044  L<Net::LDAP::Constant>,
1045  L<Net::LDAP::Control>,
1046  L<Net::LDAP::Entry>,
1047  L<Net::LDAP::Filter>,
1048  L<Net::LDAP::Message>,
1049  L<Net::LDAP::Reference>,
1050  L<Net::LDAP::Search>,
1051  L<Net::LDAP::RFC>
1052  
1053  The homepage for the perl-ldap modules can be found at 
1054  http://ldap.perl.org/.
1055  
1056  =head1 ACKNOWLEDGEMENTS
1057  
1058  This document is based on a document originally written by Russell Fulton
1059  E<lt>r.fulton@auckland.ac.nzE<gt>.
1060  
1061  Chris Ridd E<lt>chris.ridd@isode.comE<gt> for the many hours spent
1062  testing and contribution of the ldap* command line utilities.
1063  
1064  =head1 MAILING LIST
1065  
1066  A discussion mailing list is hosted by the Perl Foundation at
1067  E<lt>perl-ldap@perl.orgE<gt> No subscription is necessary!
1068  
1069  =head1 BUGS
1070  
1071  We hope you do not find any, but if you do please report them to
1072  the mailing list.
1073  
1074  If you have a patch, please send it as an attachment to the mailing
1075  list.
1076  
1077  =head1 AUTHOR
1078  
1079  Graham Barr E<lt>gbarr@pobox.comE<gt>
1080  
1081  =head1 COPYRIGHT
1082  
1083  Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program is
1084  free software; you can redistribute it and/or modify it under the same
1085  terms as Perl itself.
1086  
1087  =cut