| <?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. |
| |
| --> |
| |
| <section id="qpid_ACL"> |
| <title> |
| 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 <group-name> = [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 {<group-name>|<user-name>|"all"} {action|"all"} [object|"all"] [property=<property-value>] |
| </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> |
| <Object> |
| </entry> |
| <entry> |
| Update |
| </entry> |
| <entry> |
| |
| </entry> |
| <entry> |
| ManagementProperty::set |
| </entry> |
| <entry> |
| |
| </entry> |
| </row> |
| <row> |
| <entry> |
| <Object> |
| </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 <-- 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 |
| <user-id>@<domain> 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> |
| |
| </section> |
