Summary of issues with the Java LDAP API and resolutions

[Rob Weltman <robw@coscend.com>]

  This is a summary of questions, issues, and reservations raised by Kurt in conjunction with the last call on the Java LDAP API technical submission, and proposed responses and corrective actions.

  The changes proposed below are mostly editorial or consist of adding clarification of already implied behavior. However, items 9 and 12 involve dropping a total of three API methods of LDAPConnection, while item 14 involves adding signatures to the bind() method.

Rob


1. >4.38.1 makeSocket
>   "There may be additional makeSocket methods defined when interfaces to
>   establish TLS and SASL authentication in the Java environment have
>   been standardized."

Remove the sentence


2. > Under what circumstances is an API implementation
> required to send an Unbind request?  with disconnect()?
> if so, how do you drop the connection without sending
> an Unbind (such upon receipt of a notice of disconnect
> or an invalid PDU)?

   An API implementation is to send an Unbind request before disconnecting when the LDAPConnection.disconnect() method is called. If an API implementation receives a notice of disconnect from the server, it disconnects immediately without attempting to send an Unbind request.


> How are notices of disconnect handled?

  The client treats the connection as closed by the server (the server is expected to close the connection after sending the notice, but the client treats the connection as closed even if that does not happen).

 
> How are invalid PDUs handled?

  State in the draft that the API implementation should throw an exception if an invalid PDU is received. I propose a new result code:

100 INVALID_RESPONSE


3. > Why are RFC 2119 imperatives not used?

  Add the boilerplate text about the meaning of SHOULD, MAY, etc. Check all occurrences of should, may, must and uppercase them if appropriate, or delete them.


4. > It appears that section 1 is borrowed from RFC 2251.

  Not quite, it is borrowed from the C API draft. But add an acknowledgement of that in the acknowledgements section.


5. > The I-D represents a number of simple assertion filters
> in the form "sn=Jensen", an invalid form.  The I-D
> should use "(sn=Jensen)".
> 
> The I-D represents a number of DN in the form:
>   cn=Barbara Jensen, o=University of Michigan, c=US
> 
> An LDAPv3 generated per RFC 2253, Section 2 would
> have the form:
>   cn=Barbara Jensen,o=University of Michigan,c=US
> 
> That is, the more restrictive RFC 2253 form, as
> opposed to the RFC 1779 form, should be used.

OK


6. > I also recommend that examples use domains (example.com),
> DNs (dc=example,dc=com) and IPv4/IPv6 addresses reserved
> for examples. For IPv4, IIRC, 192.0.2.0 can be used
> (though that might be TEST numbers).  For IPv6, you can
> use the IPv6 over IPv4 address (2002::/16) based on the
> example IPv4 addresses you use.

OK


7. > I also note that some examples imports "netscape.ldap", not
> "org.ietf.ldap".  BTW, I couldn't find any packaging, name
> space requirements for this API, nor any guide as to what
> namespaces/packaging extensions to this API should be
> placed in.

  Make it org.ietf.ldap.


8. > I believe the API should support an mechanism to issue
> an Unbind request.

  Not required. Servers are allowed to immediately disconnect a client that issues an Unbind request (according to RFC 2251) and the servers we are familiar with do that. There is no difference from the client perspective between disconnecting on the one hand and disconnecting with Unbind on the other.

  See also the discussion under 2 above.


9. > I reiterate my request that a detailed security analysis should
> be undertaken before the document is progressed to the IESG.  One
> of the areas which concern me is the management of authentication
> secrets by the API.  Also, a discussion of considerations
> implementing API SASL and TLS features should be detailed.  In
> particular, the handling of TLS alerts seems an area needing
> some discussion.  There were security trade-off taken (in
> referral chasing) which should be discussed in the I-D.

  We propose dropping two methods which would allow unscrupulous code, if it was handed a live LDAPConnection, to access credentials:

  LDAPConnection.getAuthenticationPassword()
  LDAPConstraints.getReferralHandler()

  Eliminating the methods means that it will not be possible to completely serialize and then deserialize a live connection, but it will reduce the risks incurred by passing such a connection to untrusted code.

  The C API draft security section contains the following two additional sentences which we could add to the security section of the Java API draft:

"Implementations of this API SHOULD be cautious when handling authentica-
tion credentials.  In particular, keeping long-lived copies of creden-
tials without the application's knowledge is discouraged."

  For SASL and TLS features, the reader is directed to RFCs 2222 and 2246, respectively.

  As for TLS alerts, nothing is required of this draft. A TLS implementation used by an implementation of the API should conform to RFC 2246, including section 7.2 which covers the Alert Protocol (closure alerts and error alerts). Higher level protocols do not need to be aware of the Alert Protocol. If an alert leads to the TLS connection being closed, the API and application become aware of the disruption as with other connection interruptions.


10. > The 9.1 example code seems to use getStringValues() without
> a care in world to whether or not the values are compatible
> with this method.  I think a statement of the limited
> applicability of this and other String-typed value access
> methods should made, something like:
>         Applications should not use methods returning values
>         in String form unless those values are known restricted
>        to UTF-8.  Applications should not assume an attribute,
>         regardless of its syntax, is returned in string form
>         as the server is free to return any attribute using
>        ;binary transfer.

  The latter sentence is not correct, but we will add (in 4.1.4, 4.1.6, and the example):

"getStringValues() should only be called if the attribute values are known to be strings with values restricted to UTF-8. The returned Strings have undefined values if the attribute contains values not restricted to UTF-8."


11. > I would think that an referral/continuation handler provided
> the application would need to distinguish the between a
> search continuation and a referral. I note that chasing
> requirements for referrals and continuations differ, for
> example how the client needs to process an LDAP URL with
> an absent base differs.

  This has been refuted on the ldapext list.

 
> Also, I note it would be useful if methods of LDAPUrl
> (4.41.1) distinguished between an explicit and default
> parameters of an LDAP URL.  For example getScope() could return
> SCOPE_DEFAULT if an explicit scope wasn't provided.  As
> this behavior is likely only useful to applications
> doing their own referral/reference chasing, likely
> best to have some means to enable/disable this behavior.

  Unnecessary complication.

 
> What does "explicit URL string" imply?  Does it imply
> that URLs with implicit parameters are not allowed? 
> e.g. LDAPUrl("ldap://";)

  Remove "explicit".

 
> What does "full-blown LDAP URL" imply?

  A fully defined LDAP URL, with defaults assigned where not specified by the client.

 
> And "nearest X.500/LDAP"?  nearest?  X.500?

  Replace with "localhost".

 
> Also, I suggest the default port be 389 so that:
>         LDAPUrl("ldap://localhost";)
> and
>         LDAPUrl("localhost", null, null);
> are equivalent.

  Yes


12. > The TS depends upon "ldaps" and "LDAP over SSL" which
> have no technical specification of appropriate
> standard track maturity.

  Remove 4.41.13 LDAPUrl.isSecure.


13. > I would assume "thread-safe" is a term defined in the Java
> technical specification.  As this requirement is a MUST, I
> would suggest a normative reference to the specific definition
> of the term would be appropriate.

  The Java Technical Specification at http://java.sun.com/docs/books/jls/second_edition/html/memory.doc.html#30206 does not mention thread-safety, but thread-safe is not a Java term but rather a general programming concept applicable to any language supporting threads. We are not aware of a normative reference, but we could provide one from a dictionary if necessary.


> Also, how do implementations indicate which additional
> classes and methods are thread-safe?
 
  By stating that they are thread-safe in the documentation for the implementation.


14. > The bind passwd is a String.  Besides the implied
> UCS-2 -> UTF-8 conversion, I suspect there are
> password values which cannot be represented as a
> String.  I believe byte[] would be more appropriate
> type as the associated protocol field is an
> octetString (and common attributes for password
> storage hold octetString values).

  I have not heard of a single case so far, in the four years the API has been available and used, where the password could not be represented as a String, but it is legal for an LDAP bind password to contain values not in the UTF-8 character set. The following addition to the API supports those potential cases.

  For each bind() method of LDAPConnection (section 4.6.5 of http://www.ietf.org/internet-drafts/draft-ietf-ldapext-ldap-java-api-13.txt) add a corresponding method that takes a byte[] instead of a String for password.