home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_a_c / draft-ietf-asid-ldapv3-url-03.txt < prev    next >
Text File  |  1997-06-09  |  16KB  |  429 lines
  1.  
  2.  
  3.  
  4. Network Working Group                                        Tim Howes
  5. INTERNET DRAFT                                              Mark Smith
  6. OBSOLETES: RFC 1959                      Netscape Communications Corp.
  7.                                                              June 1997
  8.  
  9.  
  10.                           The LDAP URL Format
  11.                   <draft-ietf-asid-ldapv3-url-03.txt>
  12.  
  13.  
  14.  
  15. 1.  Status of this Memo
  16.  
  17. This document is an Internet-Draft.  Internet-Drafts are  working  docu-
  18. ments  of the Internet Engineering Task Force (IETF), its areas, and its
  19. working groups.  Note that other  groups  may  also  distribute  working
  20. documents as Internet-Drafts.
  21.  
  22. Internet-Drafts are draft documents valid for a maximum  of  six  months
  23. and  may  be  updated,  replaced, or obsoleted by other documents at any
  24. time.  It is inappropriate to use Internet- Drafts as reference material
  25. or to cite them other than as ``work in progress.''
  26.  
  27. To learn the current status of  any  Internet-Draft,  please  check  the
  28. ``1id-abstracts.txt''  listing  contained in the Internet- Drafts Shadow
  29. Directories on ds.internic.net (US East Coast), nic.nordu.net  (Europe),
  30. ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
  31.  
  32. 2.  Abstract
  33.  
  34. LDAP is the Lightweight Directory Access Protocol, defined in  [1],  [2]
  35. and  [3].  This document describes a format for an LDAP Uniform Resource
  36. Locator.  The format describes an LDAP search operation  to  perform  to
  37. retrieve  information from an LDAP directory. This document replaces RFC
  38. 1959. It updates the LDAP URL format for version 3 of LDAP and clarifies
  39. how  LDAP  URLs  are  resolved.  This document also defines an extension
  40. mechanism for LDAP URLs, so that future documents can extend their func-
  41. tionality,  for  example,  to provide access to new LDAPv3 extensions as
  42. they are defined.
  43.  
  44. The key words "MUST", "MAY", and "SHOULD" used in this document  are  to
  45. be interpreted as described in [6].
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55. Howes & Smith                                                   [Page 1]
  56. =0C
  57.  
  58.  
  59.  
  60.  
  61. RFC DRAFT                                                      June 1997
  62.  
  63.  
  64. 3.  URL Definition
  65.  
  66. An LDAP URL begins with the protocol prefix "ldap" and is defined by the
  67. following grammar.
  68.  
  69.     ldapurl    =3D scheme "://" [hostport] ["/"
  70.                  [dn ["?" [attributes] ["?" [scope]
  71.                  ["?" [filter] ["?" extensions]]]]]]
  72.     scheme     =3D "ldap"
  73.     attributes =3D attrdesc *("," attrdesc)
  74.     scope      =3D "base" / "one" / "sub"
  75.     dn         =3D distinguishedName from Section 3 of [1]
  76.     hostport   =3D hostport from Section 5 of RFC 1738 [5]
  77.     attrdesc   =3D AttributeDescription from Section 4.1.5 of [2]
  78.     filter     =3D filter from Section 4 of [4]
  79.     extensions =3D extension *("," extension)
  80.     extension  =3D ["!"] extype "=3D" exvalue
  81.     extype     =3D token / xtoken
  82.     exvalue    =3D LDAPString from section 4.1.2 of [2]
  83.     token      =3D <keystring> from section 4.2.1 of [3]
  84.     xtoken     =3D ("X-" / "x-") token
  85.  
  86. The "ldap" prefix indicates an entry or entries  residing  in  the  LDAP
  87. server  running  on  the  given  hostname  at  the given portnumber. The
  88. default LDAP port is TCP port 389. If no hostport is given,  the  client
  89. must  have  some apriori knowledge of an appropriate LDAP server to con-
  90. tact.
  91.  
  92. The dn is an LDAP Distinguished Name using the string  format  described
  93. in [1]. It identifies the base object of the LDAP search.
  94.  
  95. The attributes construct is used to indicate which attributes should  be
  96. returned  from  the  entry or entries.  Individual attrdesc names are as
  97. defined for AttributeDescription in [2].   If  the  attributes  part  is
  98. omitted, all user attributes of the entry or entries should be requested
  99. (e.g., by setting the attributes field AttributeDescriptionList  in  the
  100. LDAP  search  request  to  a NULL list, or (in LDAPv3) by requesting the
  101. special attribute name "*").
  102.  
  103. The scope construct is used to specify the scope of the search  to  per-
  104. form  in  the  given LDAP server.  The allowable scopes are "base" for a
  105. base object search, "one" for a one-level search, or "sub" for a subtree
  106. search.  If scope is omitted, a scope of "base" is assumed.
  107.  
  108. The filter is used to specify the search  filter  to  apply  to  entries
  109. within  the specified scope during the search.  It has the format speci-
  110. fied in [4].  If filter is omitted, a  filter  of  "(objectClass=3D*)"  i=
  111. s
  112. assumed.
  113.  
  114.  
  115.  
  116. Howes & Smith                                                   [Page 2]
  117. =0C
  118.  
  119.  
  120.  
  121.  
  122. RFC DRAFT                                                      June 1997
  123.  
  124.  
  125. The extensions construct provides the LDAP  URL  with  an  extensibility
  126. mechanism,  allowing  the  capabilities of the URL to be extended in the
  127. future. Extensions are  a  simple  comma-separated  list  of  type=3Dvalu=
  128. e
  129. pairs.  Each  type=3Dvalue  pair  is  a separate extension. These LDAP UR=
  130. L
  131. extensions are not necessarily related to any of  the  LDAPv3  extension
  132. mechanisms.  Extensions  may  be  supported or unsupported by the client
  133. resolving the URL. An extension prefixed with a '!' character (ASCII 33)
  134. is  critical.  An  extension  not  prefixed with a '!' character is non-
  135. critical.
  136.  
  137. If an extension is supported by the client, the  client  MUST  obey  the
  138. extension if the extension is critical. The client SHOULD obey supported
  139. extensions that are non-critical.
  140.  
  141. If an extension is unsupported by the client, the client MUST  NOT  pro-
  142. cess  the URL if the extension is critical.  If an unsupported extension
  143. is non-critical, the client MUST ignore the extension.
  144.  
  145. Extension types prefixed by "X-" or "x-" are reserved for use  in  bila-
  146. teral  agreements  between  communicating parties. Other extension types
  147. MUST be defined in this document, or in other standards-track documents.
  148.  
  149. One LDAP URL extension is defined in this document in the next  section.
  150. Other  documents  or  a future version of this document MAY define other
  151. extensions.
  152.  
  153. Note that any URL-illegal characters (e.g.,  spaces)  and  the  reserved
  154. character '?' (ASCII 63) occurring inside a dn, filter, or other element
  155. of an LDAP URL MUST be escaped using the % method described in RFC  1738
  156. [5].  If  a  comma  character  ',' occurs inside an extension value, the
  157. character MUST also be escaped using the % method.
  158.  
  159. 4.  The Bindname Extension
  160.  
  161. This section defines an LDAP URL extension  for  representing  the  dis-
  162. tinguished  name  for  a  client  to  use when authenticating to an LDAP
  163. directory during resolution of an LDAP URL. Clients MAY  implement  this
  164. extension.
  165.  
  166. The extension type is  "bindname".  The  extension  value  is  the  dis-
  167. tinguished  name  of the directory entry to authenticate as, in the same
  168. form as described for dn in the grammar above. The dn may  be  the  NULL
  169. string  to  specify  unauthenticated access. The extension may be either
  170. critical (prefixed with a '!' character) or non-critical  (not  prefixed
  171. with a '!' character).
  172.  
  173. If the bindname extension is critical, the client resolving the URL MUST
  174. authenticate  to the directory using the given distinguished name and an
  175.  
  176.  
  177.  
  178. Howes & Smith                                                   [Page 3]
  179. =0C
  180.  
  181.  
  182.  
  183.  
  184. RFC DRAFT                                                      June 1997
  185.  
  186.  
  187. appropriate authentication method. Note that for  a  NULL  distinguished
  188. name,  no  bind MAY be required to obtain anonymous access to the direc-
  189. tory. If the extension is non-critical,  the  client  MAY  bind  to  the
  190. directory using the given distinguished name.
  191.  
  192. 5.  URL Processing
  193.  
  194. This section describes how an LDAP URL SHOULD be resolved by a client.
  195.  
  196. First, the client obtains a connection to the LDAP server referenced  in
  197. the  URL,  or an LDAP server of the client's choice if no LDAP server is
  198. explicitly referenced.  This connection MAY be opened  specifically  for
  199. the purpose of resolving the URL or the client MAY reuse an already open
  200. connection. The connection MAY provide  confidentiality,  integrity,  or
  201. other services, e.g., using TLS. This is not specified in the URL and is
  202. at the client's discretion.
  203.  
  204. Next, the client authenticates itself to the LDAP server.  This step  is
  205. optional,  unless  the URL contains a critical bindname extension with a
  206. non-NULL value. If a bindname extension is given,  the  client  proceeds
  207. according to the section above.
  208.  
  209. If a bindname extension is not specified, the client  MAY  bind  to  the
  210. directory  using  a  appropriate dn and authentication method of its own
  211. choosing (including NULL authentication).
  212.  
  213. Next, the client performs the LDAP search  operation  specified  in  the
  214. URL.  Additional  fields  in  the  LDAP protocol search request, such as
  215. sizelimit,  timelimit,  deref,  and  anything  else  not  specified   or
  216. defaulted  in  the URL specification, MAY be set at the client's discre-
  217. tion.
  218.  
  219. Once the search has completed, the client MAY close  the  connection  to
  220. the  LDAP  server, or the client MAY keep the connection open for future
  221. use.
  222.  
  223. 6.  Examples
  224.  
  225. The following are some example LDAP URLs using the format defined above.
  226. The first example is an LDAP URL referring to the University of Michigan
  227. entry, available from an LDAP server of the client's choosing:
  228.  
  229.   ldap:///o=3DUniversity%20of%20Michigan,c=3DUS
  230.  
  231. The next example is an LDAP URL referring to the University of  Michigan
  232. entry in a particular ldap server:
  233.  
  234.   ldap://ldap.itd.umich.edu/o=3DUniversity%20of%20Michigan,c=3DUS
  235.  
  236.  
  237.  
  238. Howes & Smith                                                   [Page 4]
  239. =0C
  240.  
  241.  
  242.  
  243.  
  244. RFC DRAFT                                                      June 1997
  245.  
  246.  
  247. Both  of  these  URLs  correspond  to  a  base  object  search  of   the
  248. "o=3DUniversity   of   Michigan,   c=3DUS"   entry   using   a   filter  =
  249.  of
  250. "(objectclass=3D*)", requesting all attributes.
  251.  
  252. The next example is an LDAP URL  referring  to  only  the  postalAddress
  253. attribute of the University of Michigan entry:
  254.  
  255.   ldap://ldap.itd.umich.edu/o=3DUniversity%20of%20Michigan,c=3DUS?postalA=
  256. ddress
  257.  
  258. The corresponding LDAP search operation is the same as in  the  previous
  259. example, except that only the postalAddress attribute is requested.
  260.  
  261. The next example is an LDAP URL referring to the set of entries found by
  262. querying  the  given LDAP server on port 6666 and doing a subtree search
  263. of the University of Michigan for any entry with a common name of  "Babs
  264. Jensen", retrieving all attributes:
  265.  
  266.   ldap://host.com:6666/o=3DUniversity%20of%20Michigan,c=3DUS??sub?(cn=3DB=
  267. abs%20Jensen)
  268.  
  269. The next example is an LDAP URL referring to all children  of  the  c=3DG=
  270. B
  271. entry:
  272.  
  273.   ldap://ldap.itd.umich.edu/c=3DGB?objectClass?one
  274.  
  275. The objectClass attribute is requested to be  returned  along  with  the
  276. entries, and the default filter of "(objectclass=3D*)" is used.
  277.  
  278. The next example is an LDAP URL to retrieve the mail attribute  for  the
  279. LDAP entry named "o=3DQuestion?,c=3DUS" is given below, illustrating the =
  280. use
  281. of the escaping mechanism on the reserved character '?'.
  282.  
  283.   ldap://ldap.question.com/o=3DQuestion%3f,c=3DUS?mail
  284.  
  285. The next example illustrates the interaction between LDAP and URL  quot-
  286. ing mechanisms.
  287.  
  288.   ldap://ldap.netscape.com/o=3DBabsco,c=3DUS??(int=3D%5c00%5c00%5c00%5c04=
  289. )
  290.  
  291. The filter in this example uses the LDAP  escaping  mechanism  of  \  to
  292. encode  three zero or null bytes in the value. In LDAP, the filter would
  293. be written as  (int=3D\00\00\00\04).  Because  the  \  character  must  b=
  294. e
  295. escaped in a URL, the \'s are escaped as %5c in the URL encoding.
  296.  
  297. The final example shows the use of the bindname extension to specify the
  298. dn a client should use for authentication when resolving the URL.
  299.  
  300.   ldap:///??sub??bindname=3Dcn=3DManager%2co=3DFoo
  301.   ldap:///??sub??!bindname=3Dcn=3DManager%2co=3DFoo
  302.  
  303.  
  304.  
  305. Howes & Smith                                                   [Page 5]
  306. =0C
  307.  
  308.  
  309.  
  310.  
  311. RFC DRAFT                                                      June 1997
  312.  
  313.  
  314. The two URLs are the same, except that the second one marks the bindname
  315. extension as critical. Notice the use of the % encoding method to encode
  316. the comma in the distinguished name value in the bindname extension.
  317.  
  318. 7.  Security Considerations
  319.  
  320. General URL security considerations discussed in [5]  are  relevant  for
  321. LDAP URLs.
  322.  
  323. The use of security mechanisms when processing LDAP URLs  requires  par-
  324. ticular  care,  since  clients  may encounter many different servers via
  325. URLs, and since URLs are likely to be processed  automatically,  without
  326. user intervention. A client SHOULD have a user-configurable policy about
  327. which servers to connect to using which security mechanisms, and  SHOULD
  328. NOT make connections that are inconsistent with this policy.
  329.  
  330. Sending authentication information, no matter the mechanism, may violate
  331. a  user's  privacy requirements.  In the absence of specific policy per-
  332. mitting authentication information to be sent  to  a  server,  a  client
  333. should  use  an  anonymous connection.  (Note that clients conforming to
  334. previous LDAP URL specifications, where all  connections  are  anonymous
  335. and  unprotected,  are  consistent  with this specification; they simply
  336. have the default security policy.)
  337.  
  338. Some authentication methods, in particular reusable  passwords  sent  to
  339. the server, may reveal easily-abused information to the remote server or
  340. to eavesdroppers in transit, and should not be used  in  URL  processing
  341. unless  explicitly  permitted by policy.  Confirmation by the human user
  342. of the use of authentication information is  appropriate  in  many  cir-
  343. cumstances.   Use  of  strong  authentication methods that do not reveal
  344. sensitive information is much preferred.
  345.  
  346. The LDAP URL format allows the specification of an arbitrary LDAP search
  347. operation  to  be  performed when evaluating the LDAP URL.  Following an
  348. LDAP URL may cause unexpected results, for  example,  the  retrieval  of
  349. large  amounts of data, the initiation of a long-lived search, etc.  The
  350. security implications of resolving an LDAP URL are the same as those  of
  351. resolving an LDAP search query.
  352.  
  353. 8.  Acknowledgements
  354.  
  355. The LDAP URL format was originally defined at the University  of  Michi-
  356. gan.  This material is based upon work supported by the National Science
  357. Foundation under Grant No. NCR-9416667. The support of both the  Univer-
  358. sity  of Michigan and the National Science Foundation is gratefully ack-
  359. nowledged.
  360.  
  361. Several people  have  made  valuable  comments  on  this  document.   In
  362.  
  363.  
  364.  
  365. Howes & Smith                                                   [Page 6]
  366. =0C
  367.  
  368.  
  369.  
  370.  
  371. RFC DRAFT                                                      June 1997
  372.  
  373.  
  374. particular  RL  "Bob"  Morgan  and  Mark Wahl deserve special thanks for
  375. their contributions.
  376.  
  377. 9.  References
  378.  
  379. [1]  Lightweight Directory Access Protocol (v3): UTF-8 String  Represen-
  380.      tation  of  Distinguished  Names.   M.  Wahl, S. Kille, draft-ietf-
  381.      asid-ldapv3-dn-02.txt, March 1997.
  382.  
  383. [2]  Lightweight Directory Access Protocol (v3).  M. Wahl, T. Howes,  S.
  384.      Kille, draft-ietf-asid-ldapv3-protocol-04.txt, March 1997.
  385.  
  386. [3]  Lightweight Directory Access Protocol (v3): Attribute Syntax Defin-
  387.      itions.   M.  Wahl,  A.  Coulbeck,  T. Howes, S. Kille, draft-ietf-
  388.      asid-ldapv3-attributes-04.txt, March 1997.
  389.  
  390. [4]  A String Representation of LDAP Search Filters.  T.  Howes,  draft-
  391.      ietf-asid-ldapv3-filter.01.txt, March 1997.
  392.  
  393. [5]  Uniform Resource Locators (URL). T. Berners-Lee,  L.  Masinter,  M.
  394.      McCahill, Request for Comment (RFC) 1738, December 1994.
  395.  
  396. [6]  Key Words for use  in  RFCs  to  Indicate  Requirement  Levels,  S.
  397.      Bradner, RFC 2119, March 1997.
  398.  
  399. 10.  Author's Address
  400.  
  401.    Tim Howes
  402.    Netscape Communications Corp.
  403.    501 E. Middlefield Rd.
  404.    Mountain View, CA 94043
  405.    USA
  406.    +1 415 937-3419
  407.    howes@netscape.com
  408.  
  409.    Mark Smith
  410.    Netscape Communications Corp.
  411.    501 E. Middlefield Rd.
  412.    Mountain View, CA 94043
  413.    USA
  414.    +1 415 937-3477
  415.    mcs@netscape.com
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425. Howes & Smith                                                   [Page 7]
  426.  
  427.  
  428.  
  429.