ldap_<set/get>_option() weirdness

[Hallvard B Furuseth <h.b.furuseth@usit.uio.no>]

ldap_set_option() and ldap_get_option() have many strange behaviors.
Which of these should I document, which should be changed, and which
options and nuances below should just be omitted from the man page?

(I'm reading some libldap source and
doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt.)


* ldap.conf vs. C API:

ldap.conf options BINDDN, BASE, PORT have no equivalent C API calls.

ldap.conf options SASL_AUTHCID, SASL_AUTHZID, SASL_MECH, SASL_REALM
cannot be set with the C API.

The C API cannot access global SASL settings, only the settings for
individual sessions.  (Of these only SASL_SECPROPS can be set with the
API.)

While ldap.conf sets global settings, the C API cannot access default
TLS settings that have session-specific values.  For the other TLS
settings, the API still requires a non-NULL LDAP session handle but does
not use it.


* LDAP_OPT_PROTOCOL_VERSION:

  "Specifies the LDAP protocol version to use, and to send with
  Bind operations (since Bind operations must specify protocol version).
  *Clients should normally set this option.*
  The default is LDAP_VERSION2, even though OpenLDAP only properly
  supports LDAP_VERSION3: It can send a version 2 Bind, but will still
  treat the session as a version 3 session."

That's fairly yucky.  Maybe it's time to upgrade to LDAP_VERSION3 as the
default, even though that breaks the API draft and RFC 1823?  Or at
least warn to stderr if the version defaults to 2 for a connection,
instead of being explicitly set to 2 or 3?


* LDAP_OPT_RESTART:

  "invalue is a void* flag, outvalue points at an int.
  Specifies whether LDAP I/O operations are automatically restarted if
  they abort prematurely.
  This can be useful if an LDAP I/O operation can be interrupted
  prematurely, for example by a timer going off, or other interrupt.
  invalue LDAP_OPT_OFF = off, other values (e.g. LDAP_OPT_ON) = on.
  *outvalue is zero for off, non-zero for on.  The default is off.
  This corresponds to the RESTART option in ldap.conf(5)."

That's roughly from the LDAP C API RFC/draft.  But it seems to only
apply to select()/poll(); I'm not sure what that implies in practice.
Need that be mentioned?

Why is there a matching "RESTART" option in ldap.conf?  Should it be
documented in man5/ldap.conf.5?  It seems to me this is an option for
programmers, not users.  If ldap.conf messes with it and the program
doesn't expect that, the program might fail.  Unless the idea is that
one can fix programs with a broken LDAP module in ldap.conf...


* LDAP_OPT_DEBUG_LEVEL:

  "invalue and outvalue point at an int.
  Set/gets the debug level for LDAP library calls.
  The debug level is a bit mask of LDAP_DEBUG_* values from the file
  include/ldap_log.h in the OpenLDAP source."

How about moving the LDAP_DEBUG_* macros from ldap_log.h which is not
installed, to ldap.h which is?


* LDAP_OPT_X_TLS:

  "If the value is LDAP_OPT_X_TLS_HARD, TLS/SSL is used on all
  connections just like with ldaps:/// URLs.  Other valid values all
  mean not to do so.  Valid values: LDAP_OPT_X_TLS_NEVER,
  LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY,
  LDAP_OPT_X_TLS_HARD."

At least I think that's what it does.  What's the purpose of this
option?  To let people use ldap_init("hostname",636) to an "ldaps:///"
server when ldap_initialize() did not exist?  Yet I couldn't find a
corresponding ldap.conf option.

A boolean option with 5 possible values is also passing strange.
Maybe LDAP_OPT_X_TLS_REQUIRE_CERT defaulted to its value once.


* LDAP_OPT_ERROR_STRING, LDAP_OPT_MATCHED_DN, LDAP_OPT_REFERRAL_URLS
  (error message, matched DN and referrals from last response):

These can produce NULL outvalues, but do not accept NULL invalues.


* LDAP_OPT_URI, LDAP_OPT_HOST_NAME:

These have strange failure return values.  Sometimes LDAP_OPT_ERROR,
sometimes LDAP_PARAM_ERROR/LDAP_NO_MEMORY, and sometimes a standard LDAP
return code which they did not bother to "translate" to LDAP_OPT_*
return codes.  I'll just document that they return some other value than
LDAP_OPT_SUCCESS for error, unless someone feels like cleaning up.

Also, they have code for invalue=NULL to restore the defaults - after
the code which returns failure on invalue=NULL:-)
Well, that's an easy one.  I'll fix.


* LDAP_OPT_REFHOPLIMIT:

This is #defined in <ldap.h>, but not implemented.
Googling for it elsewhere, this seems to be the intended definition:

  Specifies the maximum number of referrals a client may chase in
  sequence.
  invalue and outvalue point at an int.


* LDAP_OPT_TIMEOUT:

This sets/reads lo->ldo_tm_api, which seems to be unused.
(invalue and *outvalue are struct timeval*.)


* options that do not verify the invalue from ldap_set_option():
  LDAP_OPT_RESULT_CODE, LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT,
  LDAP_OPT_TIMELIMIT, LDAP_OPT_X_TLS_CIPHER_SUITE,
  LDAP_OPT_X_TLS_RANDOM_FILE.

Should any of them verify?  I'm not sure when it would be an advantage
to do so, or if so to what degree they should.  E.g.:
- a server may support new LDAP_OPT_DEREF values which OpenLDAP does
  not, but a negative value could be an error.
- Verifying that the LDAP_OPT_X_TLS_RANDOM_FILE file exists might
  break programs that create the file after ldap_set_option().


* The previous setting is lost if if ldap_set_option() fails for
  LDAP_OPT_CLIENT_CONTROLS, LDAP_OPT_SERVER_CONTROLS, LDAP_OPT_TIMEOUT,
  LDAP_OPT_NETWORK_TIMEOUT.

Not sure if it's intended or if it's lazily coded.  Or if it's worth
changing, in case someone has code which depends on it.  I suppose the
current behavior can be useful, since the previous setting may be quite
unwanted after the call.


* LDAP_OPT_X_TLS_CONNECT_CB, LDAP_OPT_X_TLS_CTX, LDAP_OPT_X_TLS_SSL_CTX,
  LDAP_OPT_SOCKBUF:

These handle Sockbufs and a CTXes.  Someone else would have to provide
doc text for that.


-- 
Hallvard
For sale: Parachute. Never opened, used once, slightly stained.