NAME

Net::LDAPapi - Perl5 Module Supporting LDAP API

SYNOPSIS

use Net::LDAPapi;

See individual items and Example Programs for Usage

DESCRIPTION

This module allows Perl programmers to access and manipulate an LDAP
based Directory.

Versions beginning with 1.40 support both the original "C API" and
new "Perl OO" style interface methods.  With version 1.42, I've added
named arguments.

THE INTIAL CONNECTION

All connections to the LDAP server are started by creating a new
"blessed object" in the Net::LDAPapi class.  This can be done quite
easily by the following type of statement.

$ld = new Net::LDAPapi($hostname);

Where $hostname is the name of your LDAP server.  If you are not using
the standard LDAP port (389), you will also need to supply the portnumber.

$ld = new Net::LDAPapi($hostname,15555);

The new method can also be called with named arguments.

$ld = new Net::LDAPapi(-host=>$hostname,-port=>15389);

Note that with namd arguments, the order of the arguments is
insignificant.

BINDING

After creating a connection to the LDAP server, you will always need to
bind to the server prior to performing any LDAP related functions.  This
can be done with the 'bind' methods.

An anonymous bind can be performed without arguments:

$status = $ld->bind_s;

A simple bind can be performed by specifying the DN and PASSWORD of
the user you are authenticating as:

$status = $ld->bind_s($dn,$password);

Note that if $password above was "", you would be doing a reference bind,
which would return success even if the password in the directory was
non-null.  Thus if you were using the bind to check a password entered
with one in the directory, you should first check to see if $password was
NULL.

If your LDAP C Library supports Kerberos, you can also do Kerberos binds
simply by adding the LDAP_AUTH_KRBV4 option.  For example:

$status = $ld->bind_s($dn,$password,LDAP_AUTH_KRBV4);

For all of the above operations, you could compare $status to LDAP_SUCCESS
to see if the operation was successful.

Additionally, you could use 'bind' rather than 'bind_s' if you wanted to
use the Asynchronous LDAP routines.  The asynchronous routines would return
a MSGID rather than a status.  To find the status of an Asynchronous bind,
you would need to first obtain the result with a call to $ld->result.  See
the entry for result later in the man page, as well as the 'ldapwalk.pl'
example for further information on obtaining results from Asynchronous
operations.

The bind operations can also accept named arguments.

$status = $ld->bind_s(-dn=>$dn,-password=>$password,-type=>LDAP_AUTH_SIMPLE);

As with all other commands that support named arguments, the order of
the arguments makes no difference.

GENERATING AN ADD/MODIFY HASH

  For the add and modify routines you will need to generate
  a list of attributes and values.

  You will do this by creating a HASH table.  Each attribute in the
  hash contains associated values.  These values can be one of three
  things.

    - SCALAR VALUE    (ex. "Clayton Donley")
    - ARRAY REFERENCE (ex. ["Clayton Donley","Clay Donley"])
    - HASH REFERENCE  (ex. {"r",["Clayton Donley"]}
         note:  the value inside the HASH REFERENCE must currently
	         be an ARRAY REFERENCE.

  The key inside the HASH REFERENCE must be one of the following for a
  modify operation:
    - "a" for LDAP_MOD_ADD (Add these values to the attribute)
    - "r" for LDAP_MOD_REPLACE (Replace these values in the attribute)
    - "d" for LDAP_MOD_DELETE (Delete these values from the attribute)

  Additionally, in add and modify operations, you may specify "b" if the
  attributes you are adding are BINARY (ex. "rb" to replace binary).

  Currently, it is only possible to do one operation per add/modify
  operation, meaning you can't do something like:

     {"d",["Clayton"],"a",["Clay"]}   <-- WRONG!

  Using any combination of the above value types, you can do things like:

  %ldap_modifications = (
     "cn", "Clayton Donley",                    # Replace 'cn' values
     "givenname", ["Clayton","Clay"],           # Replace 'givenname' values
     "mail", {"a",["donley\@cig.mcel.mot.com"],  #Add 'mail' values
     "jpegphoto", {"rb",[$jpegphotodata]},      # Replace Binary jpegPhoto
  );

  Then remember to call the add or modify operations with a REFERENCE to
  this HASH.  Something like:

  $ld->modify_s($modify_dn,\%ldap_modifications);

GETTING/SETTING LDAP INTERNAL VALUES

  The following methods exist to obtain internal values within a
  Net::LDAPapi object:

  o errno - The last error-number returned by the LDAP library for this
    connection.
          ex:  print "Error Number: " . $ld->errno . "\n";

  o errstring - The string equivalent of 'errno'.
          ex:  print "Error: " . $ld->errstring . "\n";

  o ld - Reference to the actual internal LDAP structure.  Only useful if
    you needed to obtain this pointer for use in non-OO routines.
          ex:  $ldptr = $ld->ld;
  
  o entry - Reference to the current entry.  Not typically needed, but method
    supplied, just in case.
          ex:  $entry = $ld->entry;

  o msgid - Get msgid from an LDAP Result.
          ex:  $msgid = $ld->msgid;  #  msgid of current result
          ex:  $msgid = $ld->msgid($result) # msgid of $result

  o msgtype - Get msgtype from an LDAP Result.
	  ex:  $msgtype = $ld->msgtype;  # msgtype of current result
          ex:  $msgtype = $ld->msgtype($result) # msgtype of $result

  These methods are only useful for GETTING internal information, not setting
  it.  No methods are currently available for SETTING these internal values.

GETTING AND SETTING LDAP SESSION OPTIONS

  The get_option and set_option methods can be used to get and set LDAP
  session options.

  The following LDAP options can be set or gotten with these methods:
	LDAP_OPT_DEREF - Dereference
	LDAP_OPT_SIZELIMIT - Maximum Number of Entries to Return
	LDAP_OPT_TIMELIMIT - Timeout for LDAP Operations
	LDAP_OPT_REFERRALS - Follow Referrals

  For both get and set operations, the first argument is the relivant
  option.  In get, the second argument is a reference to a scalar variable
  that will contain the current value of the option.  In set, the second
  argument is the value at which to set this option.

  Examples:
    $ld->set_option(LDAP_OPT_SIZELIMIT,50);
    $ld->get_option(LDAP_OPT_SIZELIMIT,\$size);

  When setting LDAP_OPT_REFERRALS, the second argument is either LDAP_OPT_ON
  or LDAP_OPT_OFF.  Other options require a number.

  Both get_option and set_option return 0 on success and non-zero otherwise.

SSL SUPPORT

When compiled with the Netscape SDK, this module now supports SSL.
I do not have an SSL capable server, but I'm told this works.  The
functions available are:

o ssl - Turn on SSL for this connection.
  Install I/O routines to make SSL over LDAP possible
o ssl_client_init($certdbpath,$certdbhandle)
  Initialize the secure parts (called only once)

Example:
  $ld = new Net::LDAPapi("host",LDAPS_PORT);
  $ld->ssl_client_init($certdbpath,$certdbhandle);
  $ld->ssl;

SETTING REBIND PROCESS

As of version 1.42, rebinding now works properly.

The set_rebind_proc method is used to set a PERL function to supply DN,
PASSWORD, and AUTHTYPE for use when the server rebinds (for referals,
etc...).

Usage should be something like:
  $rebind_ref = \&my_rebind_proc;
  $ld->set_rebind_proc($rebind_ref);

You can then create the procedure specified.  It should return 3 values.

Example:
  sub my_rebind_proc
  {
     return($dn,$pass,LDAP_AUTH_SIMPLE);
  }

SUPPORTED METHODS

abandon MSGID

This cancels an asynchronous LDAP operation that has not completed.  It
returns an LDAP STATUS code upon completion.

Example:

  $status = ldap_abandon($ld, $msgid);

add DN ATTR

Begins an an asynchronous LDAP Add operation.  It returns a MSGID or -1
upon completion.

Example:

  %attributes = (
     "cn", ["Clayton Donley","Clay Donley"] #Add Multivalue cn
     "sn", "Donley",			      #Add sn
     "telephoneNumber", "+86-10-65551234",  #Add telephoneNumber
     "objectClass", ["person","organizationalPerson"],
                      # Add Multivalue objectClass
     "jpegphoto", {"b",[$jpegphoto]},  # Add Binary jpegphoto
  );

  $entrydn = "cn=Clayton Donley, o=Motorola, c=US";

  $msgid = $ld->add($entrydn, \%attributes);

Note that in most cases, you will need to be bound to the LDAP server
as an administrator in order to add users.

add_s DN ATTR

Synchronous version of the 'add' method.  Arguments are identical
to the 'add' method, but this operation returns an LDAP STATUS,
not a MSGID.

Example:

  $ld->add_s($entrydn, \%attributes);

See the section on creating the modify structure for more information
on populating the ATTRIBUTES field for Add and Modify operations.

bind DN PASSWORD TYPE

Asynchronous method for binding to the LDAP server.  It returns a
MSGID.

Examples:

  $msgid = $ld->bind;
  $msgid = $ld->bind("cn=Clayton Donley, o=Motorola, c=US", "abc123");

bind_s DN PASSWORD TYPE

Synchronous method for binding to the LDAP server.  It returns
an LDAP STATUS. 

Examples:

  $status = $ld->bind_s;
  $status = $ld->bind_s("cn=Clayton Donley, o=Motorola, c=US", "abc123");

compare DN ATTR VALUE

  Asynchronous method for comparing a value with the value contained
  within DN.  Returns a MSGID.

  Example:

    $msgid = $ld->compare("cn=Clayton Donley, o=Motorola, c=US", \
		$type,$value);

compare_s DN ATTR VALUE

  Synchronous method for comparing a value with the value contained
  within DN.  Returns an LDAP STATUS.

  Example:

    $status = $ld->compare_s("cn=Clayton Donley, o=Motorola, c=US", \
		$type, $value);

count_entries

Calculates and returns the number of entries in an LDAP result chain.

Example:

  $number = $ld->count_entries;

delete DN

Asynchronous method to delete DN.  Returns a MSGID or -1 if error.

Example:

  $msgid = $ld->delete("cn=Clayton Donley, o=Motorola, c=US");

delete_s DN

Synchronous method to delete DN.  Returns an LDAP STATUS.

Example:

  $status = $ld->delete_s("cn=Clayton Donley, o=Motorola, c=US");

dn2ufn DN

Converts a Distinguished Name (DN) to a User Friendly Name (UFN).
Returns a string with the UFN.

Since this operation doesn't require an LDAP object to work, you
could technically access the function directly as 'ldap_dn2ufn' rather
that the object oriented form.

Example:

  $ufn = $ld->dn2ufn("cn=Clayton Donley, o=Motorola, c=US");

explode_dn DN NOTYPES

Splits the DN into an array comtaining the separate components of
the DN.  Returns an Array.  NOTYPES is a 1 to remove attribute
types and 0 to retain attribute types.

Can also be accessed directly as 'ldap_explode_dn' if no session is
initialized and you don't want the object oriented form.

Only available when compiled with Netscape SDK.

Example:

  @components = $ld->explode_dn($dn,0);

explode_rdn RDN NOTYPES

Same as explode_dn, except that the first argument is a
Relative Distinguished Name.  NOTYPES is a 1 to remove attribute
types and 0 to retain attribute types.  Returns an array with
each component.

Can also be accessed directly as 'ldap_explode_rdn' if no session is
initialized and you don't want the object oriented form.

Only available with Netscape SDK.

Example:

  @components = $ld->explode_rdn($rdn,0);

first_attribute

Returns pointer to first attribute name found in the current entry.
Note that this only returning attribute names (ex: cn, mail, etc...).
Returns a string with the attribute name.

Returns an empty string when no attributes are available.

Example:

  $attr = $ld->first_attribute;

first_entry

Sets internal pointer to the first entry in a chain of results.  Returns
an empty string when no entries are available.

Example:

  $entry = $ld->first_entry;

get_dn

Returns a string containing the DN for the specified entry or an
empty string if an error occurs.

Example:

  $dn = $ld->get_dn;

get_values ATTR

Obtain a list of all values associated with a given attribute.
Returns an empty list if none are available.

Example:

  @values = $ld->get_values("cn");

This would put all the 'cn' values for $entry into the array @values.

get_values_len ATTR

Retrieves a set of binary values for the specified attribute.

Example:

  @values = $ld->get_values_len("jpegphoto");

This would put all the 'jpegphoto' values for $entry into the array @values.
These could then be written to a file, or further processed.

is_ldap_url URL

Checks to see if a specified URL is a valid LDAP Url.  Returns 0 on false
and 1 on true.

Example:

  $isurl = $ld->is_ldap_url("ldap://x500.my.org/o=Org,c=US");

msgfree

Frees the current LDAP result.  Returns the type of message freed.

Example:

  $type = $ld->msgfree;

modify DN MOD

Asynchronous method to modify an LDAP entry.  DN is the DN to
modify and MOD contains a hash-table of attributes and values.  If
multiple values need to be passed for a specific attribute, a
reference to an array must be passed.

Returns the MSGID of the modify operation.

Example:

  %mods = (
    "telephoneNumber", "",     #remove telephoneNumber
    "sn", "Test",              #set SN to TEST
    "mail", ["me\@abc123.com","me\@second-home.com"],  #set multivalue 'mail'
    "pager", {"a",["1234567"]},  #Add a Pager Value
    "jpegphoto", {"rb",[$jpegphoto]},  # Replace Binary jpegphoto
  );

  $msgid = $ld->modify($entrydn,\%mods);

The above would remove the telephoneNumber attribute from the entry
and replace the "sn" attribute with "Test".  The value in the "mail"
attribute for this entry would be replaced with both addresses
specified in @mail.  The "jpegphoto" attribute would be replaced with
the binary data in $jpegphoto.

modify_s DN MOD

Synchronous version of modify method.  Returns an LDAP STATUS.  See the
modify method for notes and examples of populating the MOD
parameter.

Example:

  $status = $ld->modify_s($entrydn,\%mods);

modrdn2 DN NEWRDN DELETE

  Asynchronous method to change the name of an entry.  DELETE
  is non-zero if you wish to remove the attribute values from the
  old name.  Returns a MSGID.

  Example:

    $msgid = $ld->modrdn2("cn=Clayton Donley, o=Motorola, c=US", \
		"cn=Clay Donley",0);

modrdn2_s DN NEWRDN DELETE

  Synchronous method to change the name of an entry.  DELETE is
  non-zero if you wish to remove the attribute values from the old
  name.  Returns an LDAP STATUS.

  Example:

    $status = $ld->modrdn2_s("cn=Clayton Donley, o=Motorola, c=US", \
		"cn=Clay Donley",0);

next_attribute

Similar to first_attribute, but obtains next attribute.
Returns a string comtaining the attribute name.  An empty string
is returned when no further attributes exist.

Example:

  $attr = $ld->next_attribute;

next_entry

Moves internal pointer to the next entry in a chain of search results.

Example:

  $entry = $ld->next_entry;

perror MSG

If an error occurs while performing an LDAP function, this procedure
will display it.  You can also use the err and errstring methods to
manipulate the error number and error string in other ways.

Note that this function does NOT terminate your program.  You would
need to do any cleanup work on your own.

Example:

  $ld->perror("add_s");

result MSGID ALL TIMEOUT

Retrieves the result of an operation initiated using an asynchronous
LDAP call.  Returns the type of result returned or -1 if error.

MSGID is the MSGID returned by the Asynchronous LDAP call.  Set ALL to
0 to receive entries as they arrive, or non-zero to receive all entries
before returning.  Set TIMEOUT to the number of seconds to wait for the
result, or -1 for no timeout.

Example:

  $type = $ld->result($msgid,0,1);

result2error FREEIT

Returns the LDAP error code from an LDAP result message.  FREEIT will
free the memory occupied by the result if set non-zero.

This routine also updates message returned by err and errstring
methods.

Example:

  $lderrno = $ld->result2error(0);

search BASE SCOPE FILTER ATTRS ATTRSONLY

  Begins an asynchronous LDAP search.  Returns a MSGID or -1 if an
  error occurs.  BASE is the base object for the search operation.
  FILTER is a string containing an LDAP search filter.  ATTRS is a
  reference to an array containing the attributes to return.  An
  empty array would return all attributes.  ATTRSONLY set to non-zero
  will only obtain the attribute types without values.

  SCOPE is one of the following:
		LDAP_SCOPE_BASE
		LDAP_SCOPE_ONELEVEL
		LDAP_SCOPE_SUBTREE
		
  Example:

    @attrs = ("cn","sn");    # Return specific attributes
    @attrs = ();             # Return all Attributes

    $msgid = $ld->search("o=Motorola, c=US",LDAP_SCOPE_SUBTREE, \
		"(sn=Donley),\@attrs,0);

search_s BASE SCOPE FILTER ATTRS ATTRSONLY

  Performs a synchronous LDAP search.  Returns an LDAP STATUS.  BASE
  is the base object for the search operation.  FILTER is a string
  containing an LDAP search filter.  ATTRS is a reference to an array
  containing the attributes to return.  An empty array would return all
  attributes.  ATTRSONLY set to non-zero will only obtain the attribute
  types without values.

  SCOPE is one of the following:
		LDAP_SCOPE_BASE
		LDAP_SCOPE_ONELEVEL
		LDAP_SCOPE_SUBTREE

  Example:

    @attrs = ("cn","sn");    # Return specific attributes
    @attrs = ();             # Return all attributes

    $status = $ld->search_s("o=Motorola, c=US",LDAP_SCOPE_SUBTREE, \
		"(sn=Donley)",\@attrs,0);

search_st BASE SCOPE FILTER ATTRS ATTRSONLY TIMEOUT

  Performs a synchronous LDAP search with a TIMEOUT.  See search_s
  for a description of parameters.  Returns an LDAP STATUS.  Results are
  put into RESULTS.  TIMEOUT is a number of seconds to wait before giving
  up, or -1 for no timeout.

  Example:

    $status = $ld->search_st("o=Motorola, c=US",LDAP_SCOPE_SUBTREE, \
		"(sn=Donley),[],0,3);

unbind

Unbind LDAP connection with specified SESSION handler.

Example:

  $ld->unbind;

url_parse URL

Parses an LDAP URL into separate components.  Returns a HASH reference
with the following keys, if they exist in the URL:

host		- LDAP Host
port		- LDAP Port
dn    	- LDAP Base DN
attr		- LDAP Attributes to Return (ARRAY Reference)
filter	- LDAP Search Filter
scope		- LDAP Search Scope
options	- Netscape key specifying LDAP over SSL

Example:

  $urlref = $ld->url_parse("ldap://ldap.my.org/o=My,c=US");

url_search URL ATTRSONLY

Perform an asynchronous search using an LDAP URL.  URL is the LDAP
URL to search on.  ATTRSONLY determines whether we are returning
the values for each attribute (0) or only returning the attribute
names (1).  Results are retrieved and parsed identically to a call
to the search method.

Returns a non-negative MSGID upon success.

Example:

  $msgid = $ld->url_search($my_ldap_url,0);

url_search_s URL ATTRSONLY

Synchronous version of the url_search method.  Results are retrieved
and parsed identically to a call to the search_s method.

Returns LDAP_SUCCESS upon success.

Example:

  $status = $ld->url_search_s($my_ldap_url,0);

url_search_st URL ATTRSONLY TIMEOUT

Similar to the url_search_s method, except that it allows a timeout
to be specified.  The timeout is specified as seconds.  A timeout of
0 specifies an unlimited timeout.  Results are retrieved and parsed
identically to a call to the search_st method.

Returns LDAP_SUCCESS upon success.

Example:

  $status = $ld->url_search_s($my_ldap_url,0,2);

AUTHOR

Clayton Donley, donley@wwa.com http://miso.wwa.com/~donley/

SEE ALSO

perl(1).