More about draft-ietf-ldapext-ldap-c-api-01

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

===

Can the RFC say both
   Obsoletes: RFC 1823
and
   Interested readers are referred to RFC 1823.
?

===

You might add an "Incompatibilities with RFC 1823" section.
Here is a quick draft with the changes I've noticed.

The following changes must be made to programs written for RFC 1823,
even if they don't upgrade to use LDAPv3.

* ldap_<first/next>_attribute:

  - Each returned value should now be ldap_memfree()d after use.
    In RFC 1823, they returned a pointer to a per-session buffer.
    (I don't know why that changed - it may be partly my fault, if
    it is a fault:-)

  - <ptr> should now be "freed" with ber_free(ptr,0).  RFC 1823 did
    not say we should free <ptr>, this may have been a memory leak.

  - In the type of <ptr>, void was changed to BerElement.

* Strings received from the API (ldap_get_dn and ldap_dn2ufn in
  RFC 1823) should now be freed with ldap_memfree(), not free().

* Replace accesses to the ld_* fields in an LDAP with
  ldap_<set/get>_option() calls.

* The <all> parameter to ldap_result has changed meaning:
  Nonzero values from RFC 1823 should now be LDAP_MSG_ALL (0x01).
  There is also a new possible value, LDAP_MSG_RECEIVED (0x02).

* The result type LDAP_RES_MODDN is returned where RFC 1823 returned
  LDAP_RES_MODRDN.

* New error codes (I'm not sure which ones can be returned in v2 mode):
           LDAP_CONNECT_ERROR       
           LDAP_NOT_SUPPORTED       
           LDAP_CONTROL_NOT_FOUND       
           LDAP_NO_RESULTS_RETURNED       
           LDAP_MORE_RESULTS_TO_RETURN       
           LDAP_CLIENT_LOOP       
           LDAP_REFERRAL_LIMIT_EXCEEDED       

* Different charset (UTF-8) or LDAPv3 syntax or something like that?
  (See my 'LDAPv2 with draft-ietf-ldapext-ldap-c-api-01' message.)

* Finally, some recommended changes:
  ldap_open   -> ldap_init
  ldap_modrdn -> ldap_rename
  ldap_bind(_s), ldap_kerberos_bind(_s) -> ldap_<simple/sasl>_bind(_s)
  ldap_perror, ldap_result2error -> ldap_err2string, ldap_parse*_result

===

What LDAP options do internally opened referral connections get?
The current options of the operation/session which caused the referral,
or something simpler?

I assume the API binds anonymously, since it should not save credentials
according to the Security Consideration section?

Some calls to configure how the API handles the stuff above with
automatic referrals might be useful.  And for clients that chase
referrals "by hand", something like
    ldap_set_option( ld, LDAP_OPT_COPYOPT, source_ld )
call which copies various options (size/time-limit, server/client
controls & so on) of source_ld to ld.

Another way to set up how automatic referrals are done could be to allow
ldap_<set/get>_option(NULL, ...), where (LDAP*)NULL means the default
options for connections opened with future ldap_<init/open>() calls.

Oh, and a call to unpack a referral (LDAPURL) into its (hostport, base,
...) elements would be useful for people who handle referrals "by hand".

======

15.2:

> If the caller takes responsibility for ordering values
> of sets and sequences correctly,
          ^^^^^^^^^^^^^
No, the order in sequences is significant.  (At least not the kind of
sequences I know about.)

Add "and removing DEFAULT values".

> DER output as defined in X.509 and X.680 can be produced.

If there is any interest in DER, these functions could be defined to
help with that:

  int ber_bvcmp ( struct berval *bv1, struct berval *bv2 )

    Compares bv1 and bv2 according to the DER rules.  The function
    returns an integer greater than, equal to, or less than 0, if *bv1
    is greater than, equal to, or less than *bv2 respectively.

  void ber_bvecsort ( struct berval **bvec )

    If bvec is not NULL, sort it according to the DER rules.
    bvec is NULL or a NULL-terminated array of `struct berval*'s.

-- 
Hallvard