diff --git a/ACL b/ACL
index d442b94..41a31a9 100644
--- a/ACL
+++ b/ACL
@@ -1,3 +1,5 @@
+1. What ACLs look like
+
 ACLs are:
 
   acl subject object attributes access;
@@ -15,11 +17,68 @@ Example:
 
   acl (dn=cn=root,o=fefe,c=de) (objectClass=*) * +rwdR
 
+	r	read
+	w	write
+	a	add
+	d	delete
+	R	rename DN
+
+The default is: Anonymous user can read all, write none. 
+The first useful ACL is therefore:
+
+  acl * * userPassword -r;
+
+Authenticating against a DN is always allowed. The above ACL prohibits
+getting the (hopefully encrypted) userPassword field content via LDAP.
 
 
-ACLs can have some redundancy in them, so we want to find filter strings
-in ACLs that are the same, and then only evaluate them once.  So we need
-to write the ACLs to disk like this:
+
+2. How they are evaluated
+
+ACLs are matched in the order they are given.
+The first matching ACL wins.
+
+
+
+3. How to apply them
+
+Put the ACLs in a text file, for example "acls".
+Use parse to convert your ldif into a "data" file, then use addindex to
+add indices as usual, then run acl on the new data file. For example,
+here is a Makefile example:
+
+data: ldif
+	$(TINYLDAP)/parse ldif data.new
+	$(TINYLDAP)/addindex data.new dn hu
+	$(TINYLDAP)/addindex data.new danke if
+	$(TINYLDAP)/addindex data.new ts f
+	$(TINYLDAP)/acl data.new
+	chmod a+r data.new
+	mv -f data.new data
+
+Note how the new data file is only moved over the old one after all
+other operations went through without errors.
+
+
+
+4. Where is the code?
+
+The code to read ACLs in text format, parse them, and put them into the
+binary form understood by tinyldap is in acl.c.
+
+The code that applies the ACLs in tinyldap is in the function called
+"checkacls" in tinyldap.c.
+
+
+5. Implementation notes
+
+ACL filters share the syntax of search filters.
+However, because the ACL syntax is limited we expect filters to be used
+more than ones. That's why acl.c will deduplicate filters and tinyldap
+will make sure to only match a filter once, even if it is referenced in
+multiple ACLs.
+
+The on disk format looks like this:
 
 first the filters:
 
diff --git a/README b/README
index 5b685d7..08e270e 100644
--- a/README
+++ b/README
@@ -6,9 +6,9 @@ This will be encapsulated some more eventually.
 ldapclient is the client test application.  It connects to localhost,
 makes a BindRequest and dumps the BindResponse in human readable form.
 
-tinyldap is the server test application.  It can understand BindRequest,
-some simple forms of SearchRequest, and it can even answer simple
-queries.
+tinyldap is the server test application.  It understands BindRequest,
+SearchRequest, ModifyRequest, AddRequest, and DelRequest. It does not
+yet support ModifyDNRequest.
 
 tinyldap now supports an external database representation with indexes.
 Use "parse" to create the file "data" from an LDIF file called
@@ -32,13 +32,11 @@ parse will now normalize dn before writing it to the index.  That means
 that the attribute names in dn are lowercased, ';' is converted to ','
 and spaces after ';' or ',' are removed.
 
-tinyldap support authentication.  It does not have any real effect yet,
-as tinyldap does not support ACLs, but it can be used to use LDAP for
-password checking.  To use this, you must add an index for "dn".  Most
-programs check by an attribute called "uid", so you should have that as
-well, and put the password into an attribute called "userPassword".  By
-convention, the attribute "homeDirectory" contains $HOME for that user.
-tinyldap support three kinds of passwords here:
+tinyldap supports authentication.  To use this, you must add an index
+for "dn".  Most programs check by an attribute called "uid", so you
+should have that as well, and put the password into an attribute called
+"userPassword".  By convention, the attribute "homeDirectory" contains
+$HOME for that user.  tinyldap support three kinds of passwords here:
 
   - straight MD5
     I think I took this scheme from OpenLDAP.  It's just the straight
@@ -48,6 +46,9 @@ tinyldap support three kinds of passwords here:
     You can use "md5password" (part of the tinyldap distribution) to
     calculate these passwords.
 
+    NOTE: MD5 is insecure and this method uses no salt. If you have a
+    choice, never use it!
+
   - crypt(3)
     This means you can simply copy the password from /etc/shadow.
     If your libc supports MD5 passwords in crypt (diet libc does, glibc