rfc:ldap_exop

This is an old revision of the document!


PHP RFC: LDAP EXOP

Introduction

LDAP is a broad-use standard for storing information in a tree-style manner and access it efficiently. It is especially famous for storing user accounts. EXOP are extended operations which goes further than reading/writing LDAP nodes. PHP have php-ldap module for connecting to an LDAP server and read/write datas but no way of doing EXOP operations.

Proposal

This RFC intends to add support for EXOP in php-ldap. It is based on a patch for php-ldap which is more than 10 years old and we are trying to adapt it for current code base.

New functions

In all these functions $link should be a valid LDAP connection object with a user bound to it already.

mixed ldap_exop(resource $link, string $reqoid [, string $reqdata [, string &$retoid [, string &$retdata]]])

Returns FALSE upon failure, TRUE upon success if $retoid is provided, and a result object otherwise (success with 3 params or less). Either fills $retoid and $retdata or returns a result object.

bool ldap_parse_exop(resource $link, resource $result [, string &$retoid [, string &$retdata]])

Returns TRUE upon success and FALSE upon failure. Fills $retoid and $retdata with the data from $result object.

This RFC also wish to introduce helper functions for common EXOP usage:

mixed ldap_exop_whoami(resource $link)
bool ldap_exop_passwd(resource $link, string $user, string $oldpw, string $newpw [, string &$genpw])

The first one would call whoami EXOP and return either the result or FALSE upon failure. The second one would call passwd EXOP and return TRUE or FALSE upon failure. If $newpw is empty, $genpw will be filled with the generated password for the user. If $user is empty, it affects the bound user.

The author of the original patch stated that technically ldap_start_tls is an exop helper and therefore could be renamed ldap_exop_start_tls. We feel this would be a useless BC.

The original patch (and current code) provided a possibility to get a result object from helpers as well, and provided ldap_parse_exop_* helpers to parse the result objects from these operations. We feel this is too complex and does not add anything to the RFC so we intend to leave them out.

Examples

// Call EXOP whoami and store the result in $identity
if (ldap_exop($link, LDAP_EXOP_WHO_AM_I, NULL, NULL, $identity)) {
  echo "Connected as $identity\n";
} else {
  echo "Operation failed\n";
}
// Same thing using a result object
$r = ldap_exop($link, LDAP_EXOP_WHO_AM_I);
if (($r !== FALSE) && ldap_parse_exop($link, $r, $retoid, $retdata)) {
  echo "Connected as $retdata\n";
} else {
  echo "Operation failed\n";
}
// Same thing with the helper
$identity = ldap_exop_whoami($link);
if ($identity !== FALSE) {
  echo "Connected as $identity\n";
} else {
  echo "Operation failed\n";
}
// Changing password with the helper
if (ldap_exop_passwd($link, 'uid=johndoe,dc=example,dc=com', '', 'newpassword')) {
  echo "Password changed\n";
} else {
  echo "Operation failed\n";
}

Backward Incompatible Changes

None

Proposed PHP Version(s)

Next PHP 7.x release

RFC Impact

To SAPIs

No impact

To Existing Extensions

Only php-ldap will be affected.

New Constants

The following constants will be added, containing string OIDs for the following extended operations:

  • LDAP_EXOP_START_TLS - START_TLS (RFC 4511)
  • LDAP_EXOP_MODIFY_PASSWD - PASSWD (RFC 3062)
  • LDAP_EXOP_REFRESH - REFRESH (RFC 2589)
  • LDAP_EXOP_WHO_AM_I - WHO_AM_I (RFC 4532)
  • LDAP_EXOP_TURN - TURN (RFC 4531)

Open Issues

  1. Should the function names contain the word “exop” or is it a technical detail which should be hidden from the developer?
  2. Should we include a constant for LDAP_EXOP_REFRESH, for the sake of completeness, even if this EXOP won’t be used by PHP code as all PHP LDAP operations are synchrone (in the current code state).
  3. Should helper functions return a mixed, or a boolean and have an out parameter? (“mixed ldap_exop_whoami($link)” vs “bool ldap_exop_whoami($link, &$result)”)
  4. How would someone go about generating the needed ber-encoded data to pass ldap_exop in PHP? Should this RFC also define functions to handle ber-encoded data?

Unaffected PHP Functionality

All already existing ldap related methods stays the same. This RFC only adds new ones.

Future Scope

Support for more EXOP could be added by adding other helper methods or other oid constants. Support for clients/servers controls should be added but will be part of an other RFC.

Proposed Voting Choices

Include these so readers know where you are heading and can discuss the proposed voting options.

State whether this project requires a 2/3 or 50%+1 majority (see voting)

Patches and Tests

Implementation

After the project is implemented, this section should contain

  1. the version(s) it was merged to
  2. a link to the git commit(s)
  3. a link to the PHP manual entry for the feature
  4. a link to the language specification section (if any)

References

Rejected Features

None

rfc/ldap_exop.1498548938.txt.gz · Last modified: 2017/09/22 13:28 (external edit)