Update LDAP doc

doc/scapy/layers/ldap.rst

@@ -4,9 +4,8 @@ LDAP
 Scapy fully implements the LDAPv2 / LDAPv3 messages, in addition to a very basic :class:`~scapy.layers.ldap.LDAP_Client` class.
 
 .. warning::
-    *The String Representation of LDAP Search Filters* (RFC2254) is currently **unsupported**.
-    This means that you can't use the commonly known LDAP search syntax, and instead have to use the binary format.
-    PRs are welcome !
+    Scapy's LDAP client is currently read-only. PRs are welcome !
+
 
 LDAP client usage
 -----------------
@@ -16,6 +15,7 @@ The general idea when using the :class:`~scapy.layers.ldap.LDAP_Client` class co
 - instantiating the class
 - calling :func:`~scapy.layers.ldap.LDAP_Client.connect` with the IP (this is where to specify whether to use SSL or not)
 - calling :func:`~scapy.layers.ldap.LDAP_Client.bind` (this is where to specify a SSP if authentication is desired)
+- calling :func:`~scapy.layers.ldap.LDAP_Client.search` to search data.
 
 The simplest, unauthenticated demo of the client would be something like:
 
@@ -172,9 +172,28 @@ Once the LDAP connection is bound, it becomes possible to perform requests. For
 
     client.sr1(LDAP_SearchRequest()).show()
 
-Querying more complicated requests is a bit tedious, as it *currently* requires you to build the Search request yourself.
+We can also use the :func:`~scapy.layers.ldap.LDAP_Client.search` passing a base DN, a filter (as specified by RFC2254) and a scope.\\
+
+The scope can be one of the following:
+
+- 0=baseObject: only the base DN's attributes are queried
+- 1=singleLevel: the base DN's children are queried
+- 2=wholeSubtree: the entire subtree under the base DN is included
+
 For instance, this corresponds to querying the DN ``CN=Users,DC=domain,DC=local`` with the filter ``(objectCategory=person)`` and asking for the attributes ``objectClass,name,description,canonicalName``:
 
+.. code:: python
+
+    resp = client.search(
+        "CN=Users,DC=domain,DC=local",
+        "(objectCategory=person)",
+        ["objectClass", "name", "description", "canonicalName"],
+        scope=1,  # children
+    )
+    resp.show()
+
+To understand exactly what's going on, note that the previous call is exactly identical to the following:
+
 .. code:: python
 
     resp = client.sr1(
@@ -199,4 +218,7 @@ For instance, this corresponds to querying the DN ``CN=Users,DC=domain,DC=local`
             attrsOnly=ASN1_BOOLEAN(0)
         )
     )
-    resp.show()
+
+
+.. warning::
+    Our RFC2254 parser currently does not support 'Extensible Match'.