The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Net::DSML - A perl module that supplies methods for connecting to a LDAP Directory Services Markup Language (DSML) server.

VERSION

This document describes Net::DSML version 0.003

SYNOPSIS

 Search example.
 
 # Search for entry in the directory server.
 # 
 use Net::DSML;
 use Net::DSML::Filter;
 use Net::DSML::Control;

 # Create a filter object.
 $filter = Net::DSML::Filter->new();
 # Create a subString filter
 if ( !($webfilter->subString( { type =>"initial", 
                                 attribute => $attribute, 
                                 value => $value } ) ) )
 {
    print $filter->error(), "\n";
    exit;
 }

 # Create a Control object, sort control
 $webcontrol->new( { control => "1.2.840.113556.1.4.473" } );

 # Create a DSML object.
 $dsml = Net::DSML->new({ debug => 0, 
                         url => "http://system.company.com:8080/dsml" });
 # Set the batch ID
 $dsml->setBatchId( { id => "1" } );

 if ( !( $dsml->search( { sfilter => $webfilter->getFilter(), 
                          attributes => \@attributes,
                          base => $base,
                          control => $webcontrol->getControl() } ) ) )
(
    print $dsml->error, "\n";
    exit;
 }
 # Post the xml message to the DSML server
 if ( !$dsml->send() )
 (
    print $dsml->error, "\n";
    exit;
 }
 
 # Get the xml data returned from the DSML server.
 $content = $dsml->content(); # Get data returned from the DSML server.

 # The user then uses the xml parser if their choice to break down
 # the returned xml message.


 Search example with HTTP Basic authenication.
 
 # Search for entry in the directory server.
 # 
 use Net::DSML;
 use Net::DSML::Filter;
 use Net::DSML::Control;

 # Create a filter object.
 $filter = Net::DSML::Filter->new();
 # Create a subString filter
 if ( !($webfilter->subString( { type =>"initial", 
                                 attribute => $attribute, 
                                 value => $value } ) ) )
 {
    print $filter->error(), "\n";
    exit;
 }

 # Create a Control object, sort control
 $webcontrol->new( { control => "1.2.840.113556.1.4.473" } );

 # Create a DSML object.
 $dsml = Net::DSML->new({ debug => 0, 
                         url => "https://system.company.com:9090/dsml",
                         dn => "root",
                         password => "xxY123",
                         base => \$base });
 # Set the batch ID
 $dsml->setBatchId( { id => "1" } );

 if ( !( $dsml->search( { sfilter => $webfilter->getFilter(), 
                          attributes => \@attributes,
                          control => $webcontrol->getControl() } ) ) )
(
    print $dsml->error, "\n";
    exit;
 }
 # Post the xml message to the DSML server
 if ( !$dsml->send() )
 (
    print $dsml->error, "\n";
    exit;
 }
 
 # Get the xml data returned from the DSML server.
 $content = $dsml->content(); 

 # The user then uses the xml parser if their choice to break down
 # the returned xml message.

 RootDSE example.
 
 # Get rootDSE from the DSML directory server.
 # The rootDSE method will generate the correct filter for this
 # operation.
 use Net::DSML;
 use Net::DSML::filter;

 $dsml = Net::DSML->new({ debug => 1, 
                         url => "http://system.company.com:8080/dsml" });

 if ( !$dsml->rootDSE( { attributes => \@attributes } ) )
 (
    print $dsml->error, "\n";
    exit;
 }
 # Post the xml message to the DSML server
 if ( !$dsml->send() )
 (
    print $dsml->error, "\n";
    exit;
 }
 
 # Get the xml data returned from the DSML server.
 $content = $dsml->content(); # Get data returned from the DSML server.

 # The user then uses the xml parser if their choice to break down
 # the returned xml message.

There are other examples in the scripts that are in the module`s Examples directory and the module test files are good examples of using this module.

DESCRIPTION

Net::DSML is a collection of three modules that implements a LDAP DSML API for Perl programs. The module may be used to search for and modify a LDAP directory entry.

This document assumes that the reader has some knowledge of the LDAP and DSML protocols. Information regarding Directory Services Markup Language can be found at URL: http://www.oasis-open.org/specs/index.php#dsmlv2

XML PARSER

This module does not parse the xml data returned from the DSML server. This is left up to the user, this allows the user to use the xml parser of their choice.

AUTHENICATION ISSUES

There are at least two ways of doing DSML authenication to a LDAP directory server.

One way is with the DSML authRequest, which is used when the process is capable of proxy authorization. This is the method that is supported by the OASIS documentation, in the word document on page 10, section 5.1.

Another way is with HTTP authorization. This process involes passing a DN and password to the HTTP process and allowing the http process to authenicate to the DSML server. This process can be used by the SUN One directory server ( Iplanet 5.2) and the Sun One Java Directory Server (SUN`s version 6 directory server). For this process to be allowed the dse.ldif file must be setup properly.

This software was tested using HTTP authorization.

CONSTRUCTOR

new ( {OPTIONS} )

The method new is the constructor for a new DSML oject.

Input options.

Authenication options. These must be supplied in the object constructor.

Http authorization. Input option "dn": String that contains the DN. Input option "password": String that contains the password of the DN.

Proxy authorization. Input option "proxyid": String that contains the proxy DN.

There are several possible general input options.

 Input option "base":  String that contains the LDAP search base.
 Input option "debug":  Sets the debug variable to the input value.
 Input option "error":  String that contains the LDAP onError value;
 exit or resume.  Default is exit.
 Input option "process":  String that contains the LDAP process value;
 sequential or parallel.  Default is sequential.
 Input option "order":  String that contains the LDAP order value;
 sequential or unordered.  Default is sequential.
 Input option "referral":  String that contains the referral control
 value; neverDerefAliases, derefInSearching, derefFindingBaseObj 
 or derefAlways.  Default is neverDerefAliases.
 Input option "scope":  String that contains the LDAP scope value;
 singleLevel, baseObject or wholeSubtree.  Default is singleLevel.
 Input option "size":  String that contains the size limit of the
 LDAP search.  Default is "0", unlimited.
 Input option "time":  String that contains the time limit of the
 LDAP search.  Default is "0", unlimited.
 Input option "type":  String that contains the LDAP scope value;
 true or false.  Default is false.
 Input option "url":    Specifies the LDAP server to connect to.

Examples; $dsml = Net::DSML->new({ debug => 1, url => "http://system.company.com:8080/dsml" });

Method output; Returns a new DSML object. Method error; If there is an error message then there was an error in object creation, the error message can be gotten with error method.

METHODS

setScope ( {OPTIONS} )

The method setScope sets the LDAP search scope.

There is one required input option.

 Input option "scope":  String that contains the LDAP scope value; 
 singleLevel, baseObject or wholeSubtree.  Default is singleLevel.

 $return = $dsml->setScope( { scope => "singleLevel" } );

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

setReferral ( {OPTIONS} )

The method setReferral sets the LDAP referral status.

There is one required input option.

Input option "referral": String that contains the referral control value; neverDerefAliases, derefInSearching, derefFindingBaseObj or derefAlways. Default is neverDerefAliases.

 $return = $dsml->setReferral( { referral => "neverDerefAliases" } );

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

setType ( {OPTIONS} )

The method setType sets the LDAP search scope.

There is one required input option.

 Input option "type":  String that contains the LDAP scope value; 
 true or false.  Default is false.

 $return = $dsml->setType( { type => "false" } );

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

setSize ( {OPTIONS} )

The method setSize sets the size limit of the LDAP search.

There is one required input option.

 Input option "size":  String that contains the size limit of the 
 LDAP search.  Default is "0".

 $return = $dsml->setSize( { size => 0 } );

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

setTime ( {OPTIONS} )

The method setTime sets the time limit of the LDAP search.

There is one required input option.

 Input option "time":  String that contains the time limit of the
 LDAP search.  Default is "0".

 $return = $dsml->setTime( { time => "0" } );

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

setOrder ( {OPTIONS} )

The method setOrder sets the order of the returned LDAP data.

There is one required input option.

 Input option "order":  String that contains the LDAP order value; 
 sequential or unordered.  Default is sequential.

 $return = $dsml->setOrder( { order => "sequential" } );

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

setProcess ( {OPTIONS} )

The method setProcess sets the LDAP DSML processing mode; sequential or parallel. If you use parallel you must set up a seperate unique requestId for each requested chunk of data.

There is one required input option.

 Input option "process":  String that contains the LDAP process 
 value; sequential or parallel.  Default is sequential.

 $return = $dsml->setProcess( { process => "sequential" } );

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

setOnError ( {OPTIONS} )

The method setOnError sets the LDAP DSML processing mode for errors; exit or resume.

There is one required input option.

 Input option "error":  String that contains the LDAP onError 
 value; exit or resume.  Default is exit.

 $return = $dsml->setOnError( { error => "exit" } );

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

setBatchId ( {OPTIONS} )

The method setBatchId sets the batch request id.

There is one required input option.

 Input option "id":  String that contains the LDAP operation 
 request id. Default is "batch request".

 $return = $dsml->setBatchId(  { id => "batch request" });

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

setProcessId ( {OPTIONS} )

The method setProcessId sets the LDAP process operation request id. Very important method if parallel processing is enabled because each parallel operation must have a unique request id.

There is one required input option.

 Input option "id":  String that contains the LDAP process operation 
 request id.  Default value: 1, incremented after each process.


 $return = $dsml->setProcessId(  { id => "process id" });

Method output; Returns true on success; false on error, error message can be gotten with error method.

setBase ( {OPTIONS} )

The method setBase sets the LDAP search base. This is a required method, program must set it.

There is one required input option.

 Input option "base":  String that contains the LDAP search base.

 $return = $dsml->setBase( { base => "dc=company,dc=com" } );

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

debug ( {OPTIONS} )

The method debug sets or returns the object debug flag.

There is one input option.

 Input option:  Debug value; 1 or 0.  Default is 0.

 $return = $dsml->debug( 1 );

Method output; Returns debug value.

url ( OPTIONS )

The method url sets or returns the object url value.

There is one required input option.

 Input option:  Host system name.

 $return = $dsml->url( "http://xyz.company.com:8080/dsml" );

Method output; Returns host value.

error ()

The method error returns the error message for the object. $message = $dsml->error();

size ()

The method size returns the size of the last dsml message sent to the dsml server.

$size = $dsml->size();

content ()

The method content returns the last dsml message received from the dsml server. Once the user has the content he or she can use whatever XML parser they choose.

 $returnXmlMessage = $dsml->content();

 
setProxy ( {OPTIONS} )

The method setProxy sets the LDAP authenication dn.

There is one required input option.

 Input option "dn":  String that contains the LDAP authenication dn.

 $return = $dsml->setProxy( { dn => "cn=directory manager" } );

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method. Errors will pretain to input options.

search ( {OPTIONS} )

The method search searchs the dsml server for the requested information.

There are two required input options.

 Input option "sfilter":  The filter object that contains the filter 
 string.
 Input option "attributes":  Reference to an array of attributes to get 
 information on.

There are three optional input options. Input option "id": The request ID for this operation. Input option "control": A Net::DSML::Control object output. Input option "base": The search base dn.

 $return = $dsml->search( { sfilter => $dsml->getFilter(), 
                            id => 234,
                            base => "ou=people,dc=yourcompany,dc=com",
                            control => $dsmlControl->getControl(),
                            attributes => \@attributes } );
 # Post the message to the DSML server
 $return = $dsml->send();
 # Get data returned from the DSML server.
 $content = $dsml->content(); 

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method. Errors will pretain to input options.

add ( {OPTIONS} )

The method add adds an entry into the directory server.

In order to use the add method properly, the command must do a bind to directory server. This done with the http authenication process or with the authRequest proxy dn.

There are 2 required input options. Input option "dn": The dn of the entry that you wish to add. Input option "attr": A hash of the attributes and their values that are that are to be in the entry.

There are two optional input option. Input option "control": A Net::DSML::Control object output. Input option "id": The request ID for this operation.

Example using the http authenication process.

 $dsml = Net::DSML->new( { url => $server, 
                           id => "999", 
                           dn => "xxx", 
                           passw ord => "xxx"
                         } 
                       );


 $result = $dsml->add( { 
           dn => 'cn=Barbara Jensen, o=University of Michigan, c=US',
           attr => {
                    'cn'   => ['Barbara Jensen', 'Barbs Jensen'],
                    'sn'   => 'Jensen',
                    'mail' => 'b.jensen@umich.edu',
                    'objectclass' => ['top', 'person',
                                      'organizationalPerson',
                                      'inetOrgPerson' ],
                    } } );

 # Post the xml message to the DSML server
 $return = $dsml->send();  
 # Get the data returned from the DSML server.
 $content = $dsml->content(); 

Example using the authRequest (proxy) process.

 $dsml = Net::DSML->new( { url => $server });

 $dsml->setProxy( { dn => "uid=root,ou=proxies,dc=company,dc=com");

 $result = $dsml->add( { 
           dn => 'cn=Barbara Jensen, o=University of Michigan, c=US',
           attr => {
                    'cn'   => ['Barbara Jensen', 'Barbs Jensen'],
                    'sn'   => 'Jensen',
                    'mail' => \$mail,
                    'objectclass' => ['top', 'person',
                                      'organizationalPerson',
                                      'inetOrgPerson' ],
                   } } );

 # Post the xml message to the DSML server
 $return = $dsml->send();
 # Get the data returned from the DSML server.
 $content = $dsml->content();

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

The user must parse the returned xml content message to determine what the dsml server responded with.

modify ( {OPTIONS} )

The method modify modifies attributes in an entry.

In order to use the modify method properly, the command must do a bind to directory server. This done with the http authenication process or with the authRequest proxy dn. This process is explained in the method add documentation.

There are 2 required input options. Input option "dn": The dn of the entry that you wish to add. Input option "modify": A hash of the attributes and their values that are that are to be in the entry.

There are two optional input option. Input option "control": A Net::DSML::Control object output. Input option "id": The request ID for this operation.

 $result = $dsml->modify( { 
            dn => 'cn=Barbara Jensen, o=University of Michigan, c=US',
            modify => {
                       add => {
                       'telephoneNumber' => ['214-972-1212',
                                             '972-123-0987'],
                              },
                       replace => {
                                 'mail' => \$mail,
                                  },
                       delete => {
                                 'cn'   => 'Barbs Jensen',
                                 'title'   => '',
                                  }
                        } } );

 # Post the xml message to the DSML server
 $return = $dsml->send();
 # Get the data returned from the DSML server.
 $content = $dsml->content();
 

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

The user must parse the returned xml content message to determine what the dsml server responded with.

compare ( {OPTIONS} )

The method compare, compares a specified value to a value in an attibute in the specified DN.

In order to use the compare method properly on some attributes, the command must do a bind to directory server. This done with the http authenication process or with the authRequest proxy dn. This process is explained in the method add documentation.

There are three required input options.

 Input option "dn": The dn of the entry that you wish to do the 
 comparsion on.
 Input option "attribute":  attribute to compare.
 Input option "value":  value to compare against.

There are 2 optional input options. Input option "control": A Net::DSML::Control object output. Input option "id": The request ID for this operation.

 $return = $dsml->compare( { dn => "cn=Man,ou=People,dc=xyz,dc=com", 
                             attibute => "sn", 
                             id => 123, 
                             value => "manager" } );
 # Post the xml message to the DSML server
 $return = $dsml->send();
 # Get the data returned from the DSML server.
 $content = $dsml->content();

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method. Errors will pretain to input options.

The user must parse the returned xml content message to determine what the dsml server responded with.

delete ({OPTIONS})

The method delete deletes an entry from the directory server.

In order to use the delete method properly, the command must do a bind to directory server. This done with the http authenication process or with the authRequest proxy dn. This process is explained in the method add documentation.

There is one required input option. Input option "dn": The dn of the entry that you wish to delete.

There is one optional input option. Input option "control": A Net::DSML::Control object output. Input option "id": The request ID for this operation.

 $return = $dsml->delete( { 
                  dn => "cn=Super Man,ou=People,dc=xyz,dc=com",
                  id => 1 } );
 # Post the xml message to the DSML server
 $return = $dsml->send();
 # Get the data returned from the DSML server.
 $content = $dsml->content();
 

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

The user must parse the returned xml content message to determine what the dsml server responded with.

modrdn ({OPTIONS})

The method modrdn renames an entry in the directory server.

There are three required input options. Input option "dn": The dn of the entry that you wish to delete. Input option "newsuperior": The base dn of the entry that you wish to rename. Input option "newrdn": The rdn of the new entry that you wish to create.

There are three optional input options. Input option "deleteoldrdn": The flag that controls the deleting of the entry: true or false. Input option "control": A Net::DSML::Control object output. Input option "id": The request ID for this operation.

 $return = $dsml->modrdn( { 
            dn => "cn=Super Man,ou=People,dc=xyz,dc=com",
            newrdn => "cn=Bad Boy",
            deleteoldrdn => "true",
            newsuperior => "ou=People,dc=xyz,dc=com"
                          } );
 # Post the xml message to the DSML server
 $return = $dsml->send(); 
 # Get the data returned from the DSML server.
 $content = $dsml->content();

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

The user must parse the returned xml content message to determine what the dsml server responded with.

abandon ({OPTIONS})

The method abandon request that the DSML server abandon the batch request with the given ID.

There is 1 required input option. Input option "id": The id of the batch request to abandon. This id may be referenced.

 $result = $dsml->abandon( { id => $id } );

 $return = $dsml->send();  # Post the xml message to the DSML server
 $content = $dsml->content(); # Get the data returned from the DSML server.
 

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method.

The user must parse the returned xml content message to determine what the dsml server responded with.

Ping ()

The method Ping Request to the dsml server. A Ping requests is use to confirm the existance of a dsml server on a system.

There are no inputs options for this method.

 $return = $dsml->Ping();
 # Post the xml message to the DSML server
 $return = $dsml->send();
 # Get the data returned from the DSML server.
 $content = $dsml->content();

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method. Errors will pretain to input options.

The user must parse the returned xml content message to determine if the dsml server responded.

rootDSE ( {OPTIONS} )

The method DSE the searchs the root, or dse, of the dsml server.

There is one required input option.

 Input option "attributes":  Refernce to an array of attributes to get 
 information on.

There is one optional input option. Input option "control": A Net::DSML::Control object output.

There is one optional input option. Input option "id": The request ID for this operation.

 $return = $dsml->rootDSE( { id => 21, attributes => \@attributes } );
 $return = $dsml->send();  # Post the message to the DSML server
 $content = $dsml->content(); # Get data returned from the DSML server.

The scope will automatically be set to the correct value for the user.

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method. Errors will pretain to input options.

The user must parse the returned xml content message to determine what the dsml server responded with.

getOperations

The method getOperations is used mainly by test operations. It can be used to get the operations list prior to using the send method.

getPostData

The method getPostData the xml data string that was posted to the DSML server. It is used mainly for debugging problems.

There are no required input options.

 $content = $dsml->getPostData();

Method output; Always returns 1 (true).

The user must parse the returned xml content message to determine what was posted to the dsml server.

send

The method send sends the xml data string that was created to the DSML server.

There are no required input options.

 # Post the xml message to the DSML server
 $return = $dsml->send();
 # Get the data returned from the DSML server.
 $content = $dsml->content();

Method output; Returns 1 (true) on success; 0 (false) on error, error message can be gotten with error method. This error code is from the http (LWP) process and NOT the DSML process.

The user must parse the returned xml content message to determine what was recieved from the dsml server.

DIAGNOSTICS

All of the error messages should be self explantory.

CONFIGURATION AND ENVIRONMENT

Net::DSML requires no configuration files or environment variables.

DEPENDENCIES

            Test::More          => 0
            version             => 0.680
            Readonly            => 1.030
            Class::Std::Utils   => 0.0.2
            LWP::UserAgent      => 2.0
            Carp                => 1.040

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

Currently there is a limition concerning authentication, it has not yet been implemented. This rules out any operations that modify data or access to data that requires authentication to access data.

No bugs have been reported.

Please report any bugs or feature requests to charden@pobox.com, or bug-net-dsml@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Clif Harden <charden@pobox.com>

LICENCE AND COPYRIGHT

Copyright (c) 2007, Clif Harden <charden@pobox.com>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.