2. URL Definition

An LDAP URL begins with the protocol prefix "ldap" and is defined by the following grammar, following the ABNF notation defined in [RFC4234].

  ldapurl     = scheme COLON SLASH SLASH [host [COLON port]]
                   [SLASH dn [QUESTION [attributes]
                   [QUESTION [scope] [QUESTION [filter]
                   [QUESTION extensions]]]]]
                                  ; <host> and <port> are defined
                                  ;   in Sections 3.2.2 and 3.2.3
                                  ;   of [RFC3986].
                                  ; <filter> is from Section 3 of
                                  ;   [RFC4515], subject to the
                                  ;   provisions of the
                                  ;   "Percent-Encoding" section
                                  ;   below.

  scheme      = "ldap"

  dn          = distinguishedName ; From Section 3 of [RFC4514],
                                  ; subject to the provisions of
                                  ; the "Percent-Encoding"
                                  ; section below.

  attributes  = attrdesc *(COMMA attrdesc)
  attrdesc    = selector *(COMMA selector)
  selector    = attributeSelector ; From Section 4.5.1 of
                                  ; [RFC4511], subject to the
                                  ; provisions of the
                                  ; "Percent-Encoding" section
                                  ; below.

  scope       = "base" / "one" / "sub"
  extensions  = extension *(COMMA extension)
  extension   = [EXCLAMATION] extype [EQUALS exvalue]
  extype      = oid               ; From section 1.4 of [RFC4512].

  exvalue     = LDAPString        ; From section 4.1.2 of
                                  ; [RFC4511], subject to the
                                  ; provisions of the
                                  ; "Percent-Encoding" section
                                  ; below.

  EXCLAMATION = %x21              ; exclamation mark ("!")
  SLASH       = %x2F              ; forward slash ("/")
  COLON       = %x3A              ; colon (":")
  QUESTION    = %x3F              ; question mark ("?")

The "ldap" prefix indicates an entry or entries accessible from the LDAP server running on the given hostname at the given portnumber. Note that the may contain literal IPv6 addresses as specified in Section 3.2.2 of [RFC3986].

The is an LDAP Distinguished Name using the string format described in [RFC4514]. It identifies the base object of the LDAP search or the target of a non-search operation.

The construct is used to indicate which attributes should be returned from the entry or entries.

The construct is used to specify the scope of the search to perform in the given LDAP server. The allowable scopes are "base" for a base object search, "one" for a one-level search, or "sub" for a subtree search.

The is used to specify the search filter to apply to entries within the specified scope during the search. It has the format specified in [RFC4515].

The construct provides the LDAP URL with an extensibility mechanism, allowing the capabilities of the URL to be extended in the future. Extensions are a simple comma-separated list of type=value pairs, where the =value portion MAY be omitted for options not requiring it. Each type=value pair is a separate extension. These LDAP URL extensions are not necessarily related to any of the LDAP extension mechanisms. Extensions may be supported or unsupported by the client resolving the URL. An extension prefixed with a '!' character (ASCII 0x21) is critical. An extension not prefixed with a '!' character is non-critical.

If an LDAP URL extension is implemented (that is, if the implementation understands it and is able to use it), the implementation MUST make use of it. If an extension is not implemented and is marked critical, the implementation MUST NOT process the URL. If an extension is not implemented and is not marked critical, the implementation MUST ignore the extension.

The extension type () MAY be specified using the numeric OID form (e.g., 1.2.3.4) or the descriptor form (e.g., myLDAPURLExtension). Use of the form SHOULD be restricted to registered object identifier descriptive names. See [RFC4520] for registration details and usage guidelines for descriptive names.

No LDAP URL extensions are defined in this document. Other documents or a future version of this document MAY define one or more extensions.

2.1. Percent-Encoding

A generated LDAP URL MUST consist only of the restricted set of characters included in one of the following three productions defined in [RFC3986]:

     <reserved>
     <unreserved>
     <pct-encoded>

Implementations SHOULD accept other valid UTF-8 strings [RFC3629] as input. An octet MUST be encoded using the percent-encoding mechanism described in section 2.1 of [RFC3986] in any of these situations:

  The octet is not in the reserved set defined in section 2.2 of
  [RFC3986] or in the unreserved set defined in section 2.3 of
  [RFC3986].

  It is the single Reserved character '?' and occurs inside a <dn>,
  <filter>, or other element of an LDAP URL.

  It is a comma character ',' that occurs inside an <exvalue>.

Note that before the percent-encoding mechanism is applied, the extensions component of the LDAP URL may contain one or more null (zero) bytes. No other component may.