Subject: LDAPDN (WG last call on the Java API)

From: "Kurt D. Zeilenga" <[email-masked]>
Date: Sat, 24 Mar 2001 23:47:18 -0800

>4.11 public class LDAPDN
>   A utility class representing a distinguished name (DN).
>
>4.11.1 equals
>   public static boolean equals(String dn1, String dn2)
>
>   Returns true if the two strings correspond to the same DN, after
>   appropriate normalization.

How are the DNs compared?  Per distinguished name matching
rule or by some other means.  In either case, be explicit.

What are the normalization requirements?  Depending on what
this normalization function, it might be useful to expose an
normalizer method so that callers might make use of it.

What if either DN is invalid?
What if the comparison is Undefined?

>   Parameters are:
>      dn1            String form of first DN to compare.
>      dn2            String form of second DN to compare.
>
>
>4.11.2 escapeRDN
>
>   public static String escapeRDN(String rdn)
>
>   Returns the RDN after escaping the characters requiring escaping [4].
>   For example, for the rdn ôcn=Acme, Incö, ôcn=Acme\, Incö is returned.

How are multi-valued RDNs handled?
What happens if the unescaped RDN cannot be parsed?
No byte[] support?

>   Parameters are:
>      rdn            The RDN to escape.
>
>4.11.3 unescapeRDN
>   public static String unescapeRDN(String rdn)
>
>   Returns the RDN after unescaping the characters requiring escaping
>   [4]. For example, for the rdn ôcn=Acme\, Incö, ôcn=Acme, Incö is
>   returned.

What happens if the escaped RDN cannot be parsed?
How are multi-valued RDNs handled?
What if the value is hex-encoded BER?
No byte[] support?

>   Parameters are:
>      rdn            The RDN to unescape.
>
>4.11.4 explodeDN
>
>   public static String[] explodeDN(String dn,
>                                    boolean noTypes)
>
>   Returns the individual components of a distinguished name (DN).
>
>   Parameters are:
>
>      dn             Distinguished name, e.g. "cn=Babs
>                      Jensen,ou=Accounting,o=Acme,c=us"
>
>      noTypes        If true, returns only the values of the
>                      components, and not the names, e.g. "Babs
>                      Jensen", "Accounting", "Acme", "us" - instead of
>                      "cn=Babs Jensen", "ou=Accounting", "o=Acme", and
>                      "c=us".

What happens if the DN cannot be exploded?
What if the value is escaped or hex-encoded BER?
How are multi-valued RDNs handled with and without noTypes?

>4.11.5 explodeRDN
>   public static String[] explodeRDN(String rdn,
>                                     boolean noTypes)
>
>   Returns the individual components of a relative distinguished name
>   (RDN).
>
>   Parameters are:
>      rdn            Relative distinguished name, i.e. the left-most
>                      component of a distinguished name.
>      noTypes        If true, returns only the values of the
>                      components, and not the names.

Example, please?  Does this explode "CN=bar+SN=foo"?

---

From: "Kurt D. Zeilenga" <[email-masked]>
Date: Sat, 24 Mar 2001 23:52:52 -0800

I'd also like to a see validateDN(String DN) and
validateRDN(String RDN) methods provided which
returns true iff the input is valid.

---

From: Rob Weltman <[email-masked]>
Date: Sun, 25 Mar 2001 16:10:49 -0800

> rule or by some other means.  In either case, be explicit.

  Each RDN is compared using the matching rules for the attribute of the RDN, which means that some components may be compared case-sensitively and others not.

> normalizer method so that callers might make use of it.

  As in RFC 2253:

   "Implementations MUST allow for space (' ' ASCII 32) characters to be
   present between name-component and ',', between attributeTypeAndValue
   and '+', between attributeType and '=', and between '=' and
   attributeValue.  These space characters are ignored when parsing."

  Normalization removes any such spade characters.

> What if either DN is invalid?

  IllegalArgumentException is thrown.

> What if the comparison is Undefined?

  What does that mean?

> How are multi-valued RDNs handled?

  Each of the values is compared separately, with the order not significant.

> What happens if the unescaped RDN cannot be parsed?

  IllegalArgumentException is thrown.

> No byte[] support?

  RFC 2253 states:

   "If the AttributeValue is of a type which does not have a string
   representation defined for it, then it is simply encoded as an
   octothorpe character ('#' ASCII 35) followed by the hexadecimal
   representation of each of the bytes of the BER encoding of the X.500
   AttributeValue."

> What happens if the escaped RDN cannot be parsed?

  IllegalArgumentException is thrown.

> How are multi-valued RDNs handled?

  Each component is unescaped before returning the value.

> What if the value is hex-encoded BER?

  If it meets the requirements of RFC 2253, it is unescaped and returned. Otherwise an IllegalArgumentException is thrown.

> No byte[] support?

  RFC 2253 states:

   "If the AttributeValue is of a type which does not have a string
   representation defined for it, then it is simply encoded as an
   octothorpe character ('#' ASCII 35) followed by the hexadecimal
   representation of each of the bytes of the BER encoding of the X.500
   AttributeValue."

> What happens if the DN cannot be exploded?

  IllegalArgumentException is thrown.

> What if the value is escaped or hex-encoded BER?

  If it meets the requirements of RFC 2253, it is parsed into components and returned. Otherwise an IllegalArgumentException is thrown.

> How are multi-valued RDNs handled with and without noTypes?

  As per RFC 2253, they are returned separated by the "+" character (for each RDN containing multiple values). If noTypes, the attribute name and the "=" character are omitted.

> Example, please?  Does this explode "CN=bar+SN=foo"?

  Yes.

  If noTypes, it returns {"bar", "foo"}
  If !noTypes, it returns {"CN=bar", "SN=foo"}

Rob

---

From: "Kurt D. Zeilenga" <[email-masked]>
Date: Sun, 25 Mar 2001 19:50:32 -0800

>  Each RDN is compared using the matching rules for the attribute of the RDN, which means that some components may be compared case-sensitively and others not.

Is there any specific set of matching rules an
API implementation must support?  

>   attributeValue.  These space characters are ignored when parsing."

I note that this is in section 4 which has limited applicability.
Section 3:
   Server implementations parsing a DN string generated by an
   LDAPv2 client MUST also accept (and ignore) the variants
   given in section 4 of this document.

If you require implementations to support such normalization,
I suggest you note a specific requirement otherwise some
implementation may find DNs containing extra (LDAPish) spaces
as being invalid.

>> What if the comparison is Undefined?

The implementation is unable to determine 'true'
vs. 'false' for any number of reasons... such
as not supporting a particular equality matching
rule needed to compare RDN values of each DN.

See X.501 for details.

>  Each of the values is compared separately, with the order not significant.

Compared?

How does the API determine whether a "+" in the input is part
of the value or a multiple-valued RDN separator?

>   representation of each of the bytes of the BER encoding of the X.500

How does the API determine whether a leading "#" indicates
input is BER encoded value or part of value itself?

>  Each component is unescaped before returning the value.

An how is a caller to distinguish "+" used to separate
values of the RDN and "+" which may be unescaped by this
routine?

>  If it meets the requirements of RFC 2253, it is unescaped and returned. Otherwise an IllegalArgumentException is thrown.

Which syntaxes is the API required to support BER decoding for?
Is the API required to support transliteration between T.61
and Unicode?

>   representation of each of the bytes of the BER encoding of the X.500

You said above the API decodes BER... so I not sure how this
applies.

---

From: Rob Weltman <[email-masked]>
Date: Mon, 26 Mar 2001 19:46:42 -0800

> API implementation must support?

  We could refer to RFC 2252:

"6. Syntaxes

   Servers SHOULD recognize all the syntaxes described in this section."

  There are 33 syntaxes listed there, many of them obscure and uninteresting at this point as naming attributes. I doubt there are many servers that support them all.

  We could also add a MUST for the ones commonly used as naming attributes(Directory String, IA5 String, ...?), but it is a little odd to specify that for a client API but not for a server.

> implementation may find DNs containing extra (LDAPish) spaces

  OK, normalization means (in this case) the removal of extra space in the positions defined in RFC 2253 above. An implementation of the API MUST do this.

> rule needed to compare RDN values of each DN.

  What would you suggest? It can't be a common problem since we haven't run into it. But it's not a case of invalid input. Probably the best thing would be to throw UnsupportedOperationException (which is a RuntimeException).

> of the value or a multiple-valued RDN separator?

  In this and the other questions in this message about how to parse an RDN or DN, I don't think it is a good idea to specify it in this document. It is better to refer to RFC 2253 as the authoritative source on legal syntax for RDNs and DNs, including the escaping rules.

> Is the API required to support transliteration between T.61

  No, that was eliminated in the previous round of discussion on the ldapext list about the Java LDAP API. It now only supports UTF-8, not T.61.

Rob

---

From: "Kurt D. Zeilenga" <[email-masked]>
Date: Mon, 26 Mar 2001 22:00:28 -0800

As I noted before and given your description of the normalization
function, I would very much like a method provided with this
capability.  Also, a syntax validation function might be useful
as well (though the normalization function could be used for this).

At 07:46 PM 3/26/01 -0800, Rob Weltman wrote:
>  We could also add a MUST for the ones commonly used as naming attributes(Directory String, IA5 String, ...?), 

That sounds fine... that is, MUST attributes with directoryString
syntax with caseIgnoreMatch equality matching (that covers all
attributes in the published table in RFC 2253, Section 2.  Maybe
SHOULD IA5string with caseIgnoreIA5Match as well.

> but it is a little odd to specify that for a client API but not for a server.

I agree.

>  In this and the other questions in this message about how to parse an RDN or DN, I don't think it is a good idea to specify it in this document. It is better to refer to RFC 2253 as the authoritat…

My point here is that RFC 2253 is useful if everything
is escaped... but if you unescape things you cannot
tell whether "cn=foo+sn=bar" is cn with a value of "foo+sn=bar"
OR cn with a value foo and sn of bar.

>  No, that was eliminated in the previous round of discussion on the ldapext list about the Java LDAP API. It now only supports UTF-8, not T.61.

I was noting that if you support BER encoded directoryStrings
one of the choices is TeletexString (T.61)....