path: root/qpid/doc/book/src/ACL.xml

<?xml version="1.0" encoding="utf-8"?>
<!--
 
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
   http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 
-->

<chapter xmlns:html="http://www.w3.org/1999/xhtml"><title>
      Apache Qpid : ACL
    </title><section role="h2" id="ACL-v2ACLfileformatforbrokers"><title>
            v2 ACL file format
            for brokers
          </title>
          <para>
            This new ACL implementation has been designed for implementation
            and interoperability on all Qpid brokers. It is currently
            supported in the following brokers:
          </para>

	  <table><title/><tgroup cols="2">
	  <thead>
              <row>
                <entry>
                  Broker
                </entry>
                <entry>
                  Version
                </entry>
              </row>
	  </thead>
            <tbody>
              <row>
                <entry>
                  C++
                </entry>
                <entry>
                  M4 onward
                </entry>
              </row>
              <row>
                <entry>
                  Java
                </entry>
                <entry>
                  M5 anticipated
                </entry>
              </row>
            </tbody>
          </tgroup></table>

	  <para>
            Contents
          </para>
            <itemizedlist>
              <listitem><para>
                <xref linkend="ACL-v2ACLfileformatforbrokers"/>
              </para></listitem>
              <listitem><para>
                <itemizedlist>
                  <listitem><para>
                    <xref linkend="ACL-Specification"/>
                  </para></listitem>
                  <listitem><para>
                    <xref linkend="ACL-Validation"/>
                  </para></listitem>
                  <listitem><para>
                    <xref linkend="ACL-Examplefile-3A"/>
                  </para></listitem>
                </itemizedlist>
              </para></listitem>
              <listitem><para>
                <xref linkend="ACL-DesignDocumentation"/>
              </para></listitem>
              <listitem><para>
                <itemizedlist>
                  <listitem><para>
                    <xref linkend="ACL-MappingofACLtrapstoactionandtype"/>
                  </para></listitem>
                </itemizedlist>
              </para></listitem>
              <listitem><para>
                <xref linkend="ACL-v2ACLUserGuide"/>
              </para></listitem>
              <listitem><para>
                <itemizedlist>
                  <listitem><para>
                    <xref linkend="ACL-WritingGood-2FFastACL"/>
                  </para></listitem>
                  <listitem><para>
                    <xref linkend="ACL-GettingACLtoLog"/>
                  </para></listitem>
                  <listitem><para>
                    <xref linkend="ACL-UserId-2FdomainsrunningwithCbroker"/>
                  </para></listitem>
                </itemizedlist>
              </para></listitem>
            </itemizedlist>
          <para>
            
          </para><section role="h3" id="ACL-Specification"><title>
            Specification
          </title>
          <para>
             Notes on file formats
          </para><itemizedlist>
            <listitem><para>A line starting with the character '#' will be considered a
            comment, and are ignored.
            </para></listitem>
            <listitem><para>Since the '#' char (and others that are commonly used for
            comments) are commonly found in routing keys and other AMQP
            literals, it is simpler (for now) to hold off on allowing
            trailing comments (ie comments in which everything following a
            '#' is considered a comment). This could be reviewed later once
            the rest of the format is finalized.
            </para></listitem>
            <listitem><para>Empty lines ("") and lines that contain only whitespace (any
            combination of ' ', '\f', '\n', '\r', '\t', '\v') are ignored.
            </para></listitem>
            <listitem><para>All tokens are case sensitive. "name1" != "Name1" and
            "create" != "CREATE".
            </para></listitem>
            <listitem><para>Group lists may be extended to the following line by
            terminating the line with the '\' character. However, this may
            only occur after the group name or any of the names following the
            group name. Empty extension lines (ie just a '\' character) are
            not permitted.
              
                <programlisting>
# Examples of extending group lists using a trailing '\' character

group group1 name1 name2 \
             name3 name4 \
             name5

group group2 \
             group1 \
             name6

# The following are illegal:

# '\' must be after group name
group \
      group3 name7 name8

# No empty extension lines
group group4 name9 \
                   \
             name10
</programlisting>
              
            </para></listitem>
            <listitem><para>Additional whitespace (ie more than one whitespace char)
            between and after tokens is ignored. However group and acl
            definitions must start with "group" or "acl" respectively and
            with no preceding whitespace.
            </para></listitem>
            <listitem><para>All acl rules are limited to a single line.
            </para></listitem>
            <listitem><para>Rules are interpreted from the top of the file down until the
            name match is obtained; at which point processing stops.
            </para></listitem>
            <listitem><para>The keyword "all" is reserved, and matches all individuals,
            groups and actions. It may be used in place of a group or
            individual name and/or an action - eg "acl allow all all", "acl
            deny all all" or "acl deny user1 all".
            </para></listitem>
            <listitem><para>The last line of the file (whether present or not) will be
            assumed to be "acl deny all all". If present in the file, any
            lines below this one are ignored.
            </para></listitem>
            <listitem><para>Names and group names may contain only a-z, A-Z, 0-9,
            '-','_'.
            </para></listitem>
            <listitem><para>Rules must be preceded by any group definitions they may use;
            any name not previously defined as a group will be assumed to be
            that of an individual.
            </para></listitem>
            <listitem><para>ACL rules must have the following tokens in order on a single
            line:
              <itemizedlist>
                <listitem><para>The string literal "acl";
                </para></listitem>
                <listitem><para>The permission;
                </para></listitem>
                <listitem><para>The name of a single group or individual or the keyword
                "all";
                </para></listitem>
                <listitem><para>The name of an action or the keyword "all";
                </para></listitem>
                <listitem><para>Optionally, a single object name or the keyword "all";
                </para></listitem>
                <listitem><para>If the object is present, then optionally one or more
                property name-value pair(s) (in the form property=value).
                </para></listitem>
              </itemizedlist>
            </para></listitem>
          </itemizedlist>
            <programlisting>
user = username[@domain[/realm]]
user-list = user1 user2 user3 ...
group-name-list = group1 group2 group3 ...

group &lt;group-name&gt; = [user-list] [group-name-list]


permission = [allow|allow-log|deny|deny-log]
action = [consume|publish|create|access|bind|unbind|delete|purge|update]
object = [virtualhost|queue|exchange|broker|link|route|method]
property = [name|durable|owner|routingkey|passive|autodelete|exclusive|type|alternate|queuename|schemapackage|schemaclass]

acl permission {&lt;group-name&gt;|&lt;user-name&gt;|"all"} {action|"all"} [object|"all"] [property=&lt;property-value&gt;]
</programlisting>
<!--h3--></section>
          <section role="h3" id="ACL-Validation"><title>
            Validation
          </title>
          <para>
            The new ACL file format needs to perform validation on the acl
            rules. The validation should be performed depending on the set
            value:
          </para><para>
            strict-acl-validation=none
            The default setting should be 'warn'
          </para><para>
            On validation of this acl the following checks would be expected:
          </para>
            <programlisting>
acl allow client publish routingkey=exampleQueue exchange=amq.direct
</programlisting>
          <orderedlist>
            <listitem><para>The If the user 'client' cannot be found, if the
            authentication mechanism cannot be queried then a 'user' value
            should be added to the file.
            </para></listitem>
            <listitem><para>There is an exchange called 'amq.direct'
            </para></listitem>
            <listitem><para>There is a queue bound to 'exampleQueue' on 'amq.direct'
            </para></listitem>
          </orderedlist><para>
            Each of these checks that fail will result in a log statement
            being generated.
          </para><para>
            In the case of a fatal logging the full file will be validated
            before the broker shuts down.
          </para>
<!--h3--></section>


	  <section role="h3" id="ACL-Examplefile-3A"><title>
            Example file:
          </title>
          
            <programlisting>

# Some groups
group admin ted@QPID martin@QPID
group user-consume martin@QPID ted@QPID
group group2 kim@QPID user-consume rob@QPID
group publisher group2 \
                tom@QPID andrew@QPID debbie@QPID

# Some rules
acl allow carlt@QPID create exchange name=carl.*
acl deny rob@QPID create queue
acl allow guest@QPID bind exchange name=amq.topic routingkey=stocks.ibm.#  owner=self
acl allow user-consume create queue name=tmp.*

acl allow publisher publish all durable=false
acl allow publisher create queue name=RequestQueue
acl allow consumer consume queue durable=true
acl allow fred@QPID create all
acl allow bob@QPID all queue
acl allow admin all
acl deny kim@QPID all
acl allow all consume queue owner=self
acl allow all bind exchange owner=self

# Last (default) rule
acl deny all all
</programlisting>

<!--h3--></section>
	  <!--h2--></section>

            
          <section role="h2" id="ACL-DesignDocumentation"><title>
            Design Documentation
          </title>
          <section role="h3" id="ACL-MappingofACLtrapstoactionandtype"><title>
            Mapping of ACL
            traps to action and type
          </title>
          <para>
            The C++ broker maps the ACL traps in the follow way for AMQP
            0-10:
            The Java broker currently only performs ACLs on the AMQP
            connection not on management functions:
          </para>

	  <table><title/><tgroup cols="5">
            <thead>
              <row>
                <entry>
                  Object
                </entry>
                <entry>
                  Action
                </entry>
                <entry>
                  Properties
                </entry>
                <entry>
                  Trap C++
                </entry>
                <entry>
                  Trap Java
                </entry>
              </row>
	    </thead>
	    <tbody>
              <row>
                <entry>
                  Exchange
                </entry>
                <entry>
                  Create
                </entry>
                <entry>
                  name type alternate passive durable
                </entry>
                <entry>
                  ExchangeHandlerImpl::declare
                </entry>
                <entry>
                  ExchangeDeclareHandler
                </entry>
              </row>
              <row>
                <entry>
                  Exchange
                </entry>
                <entry>
                  Delete
                </entry>
                <entry>
                  name
                </entry>
                <entry>
                  ExchangeHandlerImpl::delete
                </entry>
                <entry>
                  ExchangeDeleteHandler
                </entry>
              </row>
              <row>
                <entry>
                  Exchange
                </entry>
                <entry>
                  Access
                </entry>
                <entry>
                  name
                </entry>
                <entry>
                  ExchangeHandlerImpl::query
                </entry>
                <entry>

                </entry>
              </row>
              <row>
                <entry>
                  Exchange
                </entry>
                <entry>
                  Bind
                </entry>
                <entry>
                  name routingkey queuename owner
                </entry>
                <entry>
                  ExchangeHandlerImpl::bind
                </entry>
                <entry>
                  QueueBindHandler
                </entry>
              </row>
              <row>
                <entry>
                  Exchange
                </entry>
                <entry>
                  Unbind
                </entry>
                <entry>
                  name routingkey
                </entry>
                <entry>
                  ExchangeHandlerImpl::unbind
                </entry>
                <entry>
                  ExchangeUnbindHandler
                </entry>
              </row>
              <row>
                <entry>
                  Exchange
                </entry>
                <entry>
                  Access
                </entry>
                <entry>
                  name queuename routingkey
                </entry>
                <entry>
                  ExchangeHandlerImpl::bound
                </entry>
                <entry>
                  
                </entry>
              </row>
              <row>
                <entry>
                  Exchange
                </entry>
                <entry>
                  Publish
                </entry>
                <entry>
                  name routingKey
                </entry>
                <entry>
                  SemanticState::route
                </entry>
                <entry>
                  BasicPublishMethodHandler
                </entry>
              </row>
              <row>
                <entry>
                  Queue
                </entry>
                <entry>
                  Access
                </entry>
                <entry>
                  name
                </entry>
                <entry>
                  QueueHandlerImpl::query
                </entry>
                <entry>
                  
                </entry>
              </row>
              <row>
                <entry>
                  Queue
                </entry>
                <entry>
                  Create
                </entry>
                <entry>
                  name alternate passive durable exclusive autodelete
                </entry>
                <entry>
                  QueueHandlerImpl::declare
                </entry>
                <entry>
                  QueueDeclareHandler
                </entry>
              </row>
              <row>
                <entry>
                  Queue
                </entry>
                <entry>
                  Purge
                </entry>
                <entry>
                  name
                </entry>
                <entry>
                  QueueHandlerImpl::purge
                </entry>
                <entry>
                  QueuePurgeHandler
                </entry>
              </row>
              <row>
                <entry>
                  Queue
                </entry>
                <entry>
                  Purge
                </entry>
                <entry>
                  name
                </entry>
                <entry>
                  Management::Queue::purge
                </entry>
                <entry>
                  
                </entry>
              </row>
              <row>
                <entry>
                  Queue
                </entry>
                <entry>
                  Delete
                </entry>
                <entry>
                  name
                </entry>
                <entry>
                  QueueHandlerImpl::delete
                </entry>
                <entry>
                  QueueDeleteHandler
                </entry>
              </row>
              <row>
                <entry>
                  Queue
                </entry>
                <entry>
                  Consume
                </entry>
                <entry>
                  name (possibly add in future?)
                </entry>
                <entry>
                  MessageHandlerImpl::subscribe
                </entry>
                <entry>
                  BasicConsumeMethodHandler
                  BasicGetMethodHandler
                </entry>
              </row>
              <row>
                <entry>
                  &lt;Object&gt;
                </entry>
                <entry>
                  Update
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  ManagementProperty::set
                </entry>
                <entry>
                  
                </entry>
              </row>
              <row>
                <entry>
                  &lt;Object&gt;
                </entry>
                <entry>
                  Access
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  ManagementProperty::read
                </entry>
                <entry>
                  
                </entry>
              </row>
              <row>
                <entry>
                  Link
                </entry>
                <entry>
                  Create
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  Management::connect
                </entry>
                <entry>
                  
                </entry>
              </row>
              <row>
                <entry>
                  Route
                </entry>
                <entry>
                  Create
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  Management:: -createFederationRoute-
                </entry>
                <entry>
                  
                </entry>
              </row>
              <row>
                <entry>
                  Route
                </entry>
                <entry>
                  Delete
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  Management:: -deleteFederationRoute-
                </entry>
                <entry>
                  
                </entry>
              </row>
              <row>
                <entry>
                  Virtualhost
                </entry>
                <entry>
                  Access
                </entry>
                <entry>
                  name
                </entry>
                <entry>
                  TBD
                </entry>
                <entry>
                  ConnectionOpenMethodHandler
                </entry>
              </row>
            </tbody>
          </tgroup></table><para>
            Management actions that are not explicitly given a name property
            it will default the name property to management method name, if
            the action is 'W' Action will be 'Update', if 'R' Action will be
            'Access'.
          </para><para>
            for example, if the mgnt method 'joinCluster' was not mapped in
            schema it will be mapped in ACL file as follows
          </para>

	  <table><title/><tgroup cols="3">
            <thead>
              <row>
                <entry>
                  Object
                </entry>
                <entry>
                  Action
                </entry>
                <entry>
                  Property
                </entry>
              </row>
	    </thead>
	    <tbody>
              <row>
                <entry>
                  Broker
                </entry>
                <entry>
                  Update
                </entry>
                <entry>
                  name=joinCluster
                </entry>
              </row>
            </tbody>
          </tgroup></table>

	<!--h3--></section>
	<!--h2--></section>


	<section role="h2" id="ACL-v2ACLUserGuide"><title>
            v2 ACL User Guide
          </title>
          <section role="h3" id="ACL-WritingGood-2FFastACL"><title>
            Writing Good/Fast ACL
          </title>
          <para>
            The file gets read top down and rule get passed based on the
            first match. In the following example the first rule is a dead
            rule. I.e. the second rule is wider than the first rule. DON'T do
            this, it will force extra analysis, worst case if the parser does
            not kill the dead rule you might get a false deny.
          </para>
            <programlisting>
allow peter@QPID create queue name=tmp &lt;-- dead rule!!
allow peter@QPID create queue
deny all all
</programlisting>
          <para>
            By default files end with
          </para>
            <programlisting>
deny all all
</programlisting>
          <para>
            the mode of the ACL engine can be swapped to be allow based by
            putting the following at the end of the file
          </para>
            <programlisting>
allow all all
</programlisting>
          <para>
            Note that 'allow' based file will be a LOT faster for message
            transfer. This is because the AMQP specification does not allow
            for creating subscribes on publish, so the ACL is executed on
            every message transfer. Also, ACL's rules using less properties
            on publish will in general be faster.
          </para>
	  <!--h3--></section>

	  <section role="h3" id="ACL-GettingACLtoLog"><title>
            Getting ACL to Log
          </title>
          <para>
            In order to get log messages from ACL actions use allow-log and
            deny-log for example
          </para>
            <programlisting>
allow-log john@QPID all all
deny-log guest@QPID all all
</programlisting>
	  <!--h3--></section>

          <section role="h3" id="ACL-UserId-2FdomainsrunningwithCbroker"><title>
            User Id /
            domains running with C++ broker
          </title>
          <para>
            The user-id used for ACL is taken from the connection user-id.
            Thus in order to use ACL the broker authentication has to be
            setup. i.e. (if --auth no is used in combination with ACL the
            broker will deny everything)
          </para><para>
            The user id in the ACL file is of the form
            &lt;user-id&gt;@&lt;domain&gt; The Domain is configured via the
            SASL configuration for the broker, and the domain/realm for qpidd
            is set using --realm and default to 'QPID'.
          </para><para>
            To load the ACL module use, load the acl module cmd line or via
            the config file
          </para>
            <programlisting>
./src/qpidd --load-module src/.libs/acl.so
</programlisting>
          <para>
            The ACL plugin provides the following option '--acl-file'. If do
            ACL file is supplied the broker will not enforce ACL. If an ACL
            file name is supplied, and the file does not exist or is invalid
            the broker will not start.
          </para>
            <programlisting>
ACL Options:
  --acl-file FILE       The policy file to load from, loaded from data dir
</programlisting>

	  <!--h3--></section>
	<!--h2--></section>

</chapter>