diff options
Diffstat (limited to 'qpid/doc/book/src/old/ACL.xml')
| -rw-r--r-- | qpid/doc/book/src/old/ACL.xml | 800 |
1 files changed, 800 insertions, 0 deletions
diff --git a/qpid/doc/book/src/old/ACL.xml b/qpid/doc/book/src/old/ACL.xml new file mode 100644 index 0000000000..ceb7cecb23 --- /dev/null +++ b/qpid/doc/book/src/old/ACL.xml @@ -0,0 +1,800 @@ +<?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>ACL Support in Qpid Broker Versions</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>Mapping ACL Traps</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>Mapping Management Actions to ACL</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> |