NAME

Net::LDAP::Gateway - Infrastructure to build LDAP gateways

SYNOPSIS

  use Net::LDAP::Gateway;

DESCRIPTION

This module provides a set of low level functions to encode and decode LDAP packets

EXPORT

The following functions can be imported from this module:

$normalized = ldap_dn_normalize($dn)

returns a normalized version of the given dn.

$len = ldap_peek_message($buffer)

($len, $msgid, $op, $more) = ldap_peek_message($buffer)

If enough data is available in buffer, this function returns the size of the incomming packet. Otherwise it returns undef.

When called in list context, besides the packet len, if enough data is available from the buffer, this function also returns the message ID, the LDAP operation code and depending on the packet type, the dn or the error code.

($msgid, $op, $data) = ldap_shift_message($buffer)

Extracts and parses the next LDAP message available from $buffer.

$msgid is the message id.

$op is the number associated to the requested operation as defined by the LDAP specification (symbolic names for those constants can be imported from Net::LDAP::Gateway::Constant).

$data is a hash representing all the data available on the packet as follows:

LDAP_OP_BIND_REQUEST [0]

  $data = { version  => $protocol_version,
            dn       => $bind_dn,
            method   => $auth_method,
            %method_data
  }

$auth_method == LDAP_AUTH_SIMPLE

  %method_data  =(password => $password)

other authentication methods are currently not supported

LDAP_OP_UNBIND_REQUEST [2]

The unbind request does not carry any extra data:

  $data = {}

LDAP_OP_SEARCH_REQUEST [3]

  $data = { base_dn       => $base_dn,
            scope         => $scope,
            deref_aliases => $deref,
            size_limit    => $sl,      # optional
            time_limit    => $tl,      # optional
            types_only    => 1,        # optional
            filter        => \@filter
            attributes    => \@attr,   # optional
  }

$scope can take the values LDAP_SCOPE_BASE_OBJECT [0], LDAP_SCOPE_SINGLE_LEVEL [1] or LDAP_SCOPE_WHOLE_SUBTREE [2].

$deref can take the values LDAP_DEREF_ALIASES_NEVER [0], LDAP_DEREF_ALIASES_IN_SEARCHING [1], LDAP_DEREF_ALIASES_FINDING_BASE_OBJ [2] or LDAP_DEREF_ALIASES_ALWAYS [3]

LDAP_OP_MODIFY_REQUEST [6]

  $data = { dn      => $dn,
            add     => $add,
            changes => \@changes
  }

  @changes = ( { operation => $op,
                 attribute => $attribute,
                 values    => \@values },
                 ...
             )

$op can take the values LDAP_MODOP_REPLACE, LDAP_MODOP_ADD or LDAP_MODOP_DELETE.

LDAP_OP_ADD_REQUEST [8]

  $data = { dn     => $dn,
            $attr1 => \@values1,
            $attr2 => \@values2,
            ...
  }

LDAP_OP_DELETE_REQUEST [10]

  $data = { dn => $dn }

LDAP_OP_MODIFY_DN_REQUEST [12]

  $data = { dn             => $dn,
            new_rdn        => $new_rdn,
            delete_old_rdn => 1,          # optional
            new_superior   => $superior,  # optional

LDAP_OP_COMPARE_REQUEST [14]

  $data = { dn        => $dn,
            attribute => $attr,
            value     => $value }

LDAP_OP_ABANDON_REQUEST [16]

  $data = { message_id => $message_id }

LDAP_OP_EXTENDED_REQUEST [23]

  $data = { oid   => $oid,
            value => $value }

LDAP_OP_BIND_RESPONSE [1]

  $data = { result => $result_code,
            matched_dn => $dn,
            message => $message,
            referrals => \@referrals,        # optional
            sasl_credentials => $credentials # optional
  }

LDAP_OP_SEARCH_ENTRY_RESPONSE [5]

  $data = { dn => $entry_dn,
            $attr1 => \@values1,
            $attr2 => \@values2,
            ...
  }

LDAP_OP_SEARCH_DONE_RESPONSE [5]

LDAP_OP_MODIFY_RESPONSE [7]

LDAP_OP_ADD_RESPONSE [9]

LDAP_OP_DELETE_RESPONSE [11]

LDAP_OP_MODIFY_DN_RESPONSE [13]

LDAP_OP_COMPARE_RESPONSE [15]

LDAP_OP_EXTENDED_RESPONSE [24]

  $data = { result     => $result_code,
            matched_dn => $dn,
            message    => $message,
            referrals  => \@referrals    # optional
  }

$result_code contains the status of the operation (see "Error codes" in Net::LDAP::Gateway::Constant).

$msg = ldap_pack_message_ref($msgid, $op, \%data)

$msg = ldap_pack_bind_request_ref($msgid, \%data)

$msg = ldap_pack_bind_response_ref($msgid, \%data)

$msg = ldap_pack_unbind_request_ref($msgid, \%data)

$msg = ldap_pack_search_request_ref($msgid, \%data)

$msg = ldap_pack_search_entry_response_ref($msgid, \%data)

$msg = ldap_pack_search_done_response_ref($msgid, \%data)

$msg = ldap_pack_modify_request_ref($msgid, \%data)

$msg = ldap_pack_modify_response_ref($msgid, \%data)

$msg = ldap_pack_add_request_ref($msgid, \%data)

$msg = ldap_pack_add_response_ref($msgid, \%data)

$msg = ldap_pack_delete_request_ref($msgid, \%data)

$msg = ldap_pack_delete_response_ref($msgid, \%data)

$msg = ldap_pack_modify_dn_request_ref($msgid, \%data)

$msg = ldap_pack_modify_dn_response_ref($msgid, \%data)

$msg = ldap_pack_compare_request_ref($msgid, \%data)

$msg = ldap_pack_compare_response_ref($msgid, \%data)

$msg = ldap_pack_abandon_request_ref($msgid, \%data)

$msg = ldap_pack_extended_request_ref($msgid, \%data)

$msg = ldap_pack_extended_response_ref($msgid, \%data)

These functions take a $msgid and a reference to a hash containing the message data and return the LDAP message.

The data structured passed must be as documented on ldap_shift_message.

$msg = ldap_pack_bind_request($msgid, ...)

$msg = ldap_pack_bind_response($msgid, $result, $matched_dn, $message, \@referrals, $SASL_creds)

$msg = ldap_pack_unbind_request($msgid)

$msg = ldap_pack_search_request($msgid, $base_dn, $scope, $deref, $size_limit, $time_limit, $types_only, $filter, \@attributes)

$msg = ldap_pack_search_entry_response($msgid, $dn, $attr1 => \@values1, $attr2 => \@values2)

$msg = ldap_pack_search_done_response($msgid, $result, $matched_dn, $message, \@referrals)

$msg = ldap_pack_modify_request($msgid, ...)

$msg = ldap_pack_modify_response($msgid, $result, $matched_dn, $message, \@referrals)

$msg = ldap_pack_add_request($msgid, ...)

$msg = ldap_pack_add_response($msgid, $result, $matched_dn, $message, \@referrals)

$msg = ldap_pack_delete_request($msgid, ...)

$msg = ldap_pack_delete_response($msgid, $result, $matched_dn, $message, \@referrals)

$msg = ldap_pack_modify_dn_request($msgid, ...)

$msg = ldap_pack_modify_dn_response($msgid, $result, $matched_dn, $message, \@referrals)

$msg = ldap_pack_compare_request($msgid, ...)

$msg = ldap_pack_compare_response($msgid, $result, $matched_dn, $message, \@referrals)

$msg = ldap_pack_abandon_request($msgid, ...)

$msg = ldap_pack_extended_request($msgid, ...)

$msg = ldap_pack_extended_response($msgid, ...)

These functions take a $msgid and a list of arguments and return the corresponding LDAP message.

TODO

- add support for SASL authentication

- add support for common controls and extensions (requests welcome!)

- support controls in packing methods

SEE ALSO

Other Perl LDAP related modules: Net::LDAP, Net::LDAPapi, Net::LDAP::Server.

LDAP RFCs 4511, 4513, 4515, 4517, 4519, 4510, 4512, 4514, 4516 and 4518.

AUTHOR

Salvador Fandiño, <sfandino@yahoo.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009, 2010, 2011 by Qindel Formacion y Servicios S.L.

This Perl module is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This Perl module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this package. If not, see http://www.gnu.org/licenses/.