BIND 10 trac2066, updated. 1bcbd2eeafca5c1e1fbed6a5e8eed17487bbbedd [2066] Hopefully more understandable description of ACLs

[BIND 10 source code commits]

The branch, trac2066 has been updated
       via  1bcbd2eeafca5c1e1fbed6a5e8eed17487bbbedd (commit)
      from  0b2ed3a094e9c083d22df78c89c503c80d4e2dbf (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 1bcbd2eeafca5c1e1fbed6a5e8eed17487bbbedd
Author: Michal 'vorner' Vaner <michal.vaner at nic.cz>
Date:   Fri Aug 10 15:39:59 2012 +0200

    [2066] Hopefully more understandable description of ACLs
    
    Including something like more formal grammar of them.

-----------------------------------------------------------------------

Summary of changes:
 doc/guide/bind10-guide.xml |   51 +++++++++++++++++++++++++++++++-------------
 1 file changed, 36 insertions(+), 15 deletions(-)

-----------------------------------------------------------------------
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index 97437c8..772bd82 100644
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -1316,27 +1316,48 @@ TODO
       <para>
         An ACL, or Access Control List, is a way to describe if a request
         is allowed or disallowed. The principle is, there's a list of rules.
-        A request either matches the rule or it doesn't. If it matches,
-        a decision is made and no more ACL processing happens. If it does
-        not match, the processing moves to the next rule. If there are
-        no more rules, a default action is taken.
+        Each rule is a name-value mapping (a dictionary, in the JSON
+        terminology). Each rule must contain exactly one mapping called
+        "action", which describes what should happen if the rule applies.
+        There may be more mappings, calld matches, which describe the
+        conditions under which the rule applies.
       </para>
 
       <para>
-        Each element in the ACL is a dictionary. There's exactly one
-        <varname>action</varname> element. This element describes the
-        decision taken when the rule matches. If it is set to
-        "ACCEPT", the request processed. In case of "REJECT", the request
-        is not processed and an error message is sent back (what it means
-        depends on which ACL it is). The action of "DROP" does not
-        process the request and sends no answer — pretending the
-        request never came (which means the sender might resend it).
+        When there's a query, the first rule is examined. If it matches, the
+        action in it is taken. If not, next rule is examined. If there are no
+        more rules to examine, a default action is taken.
       </para>
 
       <para>
-        Other elements inside the rule describe the properties a request
-        must have to match. The request must match all the properties
-        in the check.
+        There are three possible "action" values. The "ACCEPT" value means
+        the query is handled. If it is "REJECT", the query is not answered,
+        but a polite error message is sent back (if that makes sense in the
+        context). The "DROP" action acts like a black hole. The query is
+        not answered and no error message is sent.
+      </para>
+
+      <para>
+        If there are multiple matching conditions inside the rule, all of
+        them must be satisfied for the rule to apply. This can be used,
+        for example, to require the query to be signed by a TSIG key and
+        originate from given address.
+      </para>
+
+      <para>
+        This is encoded in form of JSON. Semi-formal description could look
+        something like this. It is described in more details below.
+        <!-- FIXME: Is <screen> really the correct one?-->
+        <screen>ACL := [ RULE, RULE, ... ]
+RULE := { "action": "ACCEPT"|"REJECT"|"DROP", MATCH, MATCH, ... }
+RULE_RAW := { MATCH, MATCH, ... }
+MATCH := FROM_MATCH|KEY_MATCH|NOT_MATCH|OR_MATCH|AND_MATCH|...
+FROM_MATCH := "from": "<ip range>
+KEY_MATCH := "key": "<key name>
+NOT_MATCH := "NOT": RULE_RAW
+OR_MATCH := "ANY": [ RULE_RAW, RULE_RAW, ... ]
+AND_MATCH := "ALL": [ RULE_RAW, RULE_RAW, ... ]
+</screen>
       </para>
 
       <section>