qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Qpid > ACL
Date Wed, 12 May 2010 14:42:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/21/_/styles/combined.css?spaceKey=qpid&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="http://cwiki.apache.org/confluence/display/qpid/ACL">ACL</a></h2>
    <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~rajith">Rajith
Attapattu</a>
    </h4>
        <br/>
                         <h4>Changes (3)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >* The keyword &quot;all&quot;
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 &quot;acl allow all all&quot;, &quot;acl
deny all all&quot; or &quot;acl deny user1 all&quot;. <br>* The last line
of the file (whether present or not) will be assumed to be &quot;acl deny all all&quot;.
If present in the file, any lines below this one are ignored. <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">*
Names and group names may contain only a-z, A-Z, 0-9, &#39;-&#39;,&#39;_&#39;.
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">*
Property names, Usernames and group names may contain only *a-z , A-Z , 0-9 , &#39;-&#39;
, &#39;_&#39; &amp;amp; &#39;.&#39;*. <br></td></tr>
            <tr><td class="diff-unchanged" >* 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. <br>* ACL rules must have the following tokens in order on a
single line: <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code} <br></td></tr>
            <tr><td class="diff-changed-lines" >user = <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">username[@domain[/realm]]</span>
<span class="diff-added-words"style="background-color: #dfd;">username[/domain[@realm]]</span>
<br></td></tr>
            <tr><td class="diff-unchanged" >user-list = user1 user2 user3 ...
<br>group-name-list = group1 group2 group3 ... <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h2><a name="ACL-v2ACLfileformatforbrokers"></a>v2 ACL file format
for brokers</h2>

<p>This new ACL implementation has been designed for implementation and interoperability
on all Qpid brokers. It is currently supported in the following brokers:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Broker </th>
<th class='confluenceTh'> Version </th>
</tr>
<tr>
<td class='confluenceTd'> C++    </td>
<td class='confluenceTd'> M4 onward </td>
</tr>
<tr>
<td class='confluenceTd'> Java   </td>
<td class='confluenceTd'> M5 anticipated </td>
</tr>
</tbody></table>
</div>


<p><b>Contents</b></p>

<div>
<ul>
    <li><a href='#ACL-v2ACLfileformatforbrokers'>v2 ACL file format for brokers</a></li>
<ul>
    <li><a href='#ACL-Specification'>Specification</a></li>
    <li><a href='#ACL-Validation'>Validation</a></li>
    <li><a href='#ACL-Examplefile%3A'>Example file:</a></li>
</ul>
    <li><a href='#ACL-DesignDocumentation'>Design Documentation</a></li>
<ul>
    <li><a href='#ACL-MappingofACLtrapstoactionandtype'>Mapping of ACL traps to
action and type</a></li>
</ul>
    <li><a href='#ACL-v2ACLUserGuide'>v2 ACL User Guide</a></li>
<ul>
    <li><a href='#ACL-WritingGood%2FFastACL'>Writing Good/Fast ACL</a></li>
    <li><a href='#ACL-GettingACLtoLog'>Getting ACL to Log</a></li>
    <li><a href='#ACL-UserId%2FdomainsrunningwithCbroker'>User Id / domains running
with C++ broker</a></li>
</ul>
</ul></div>


<p><a name="ACL-specification"></a></p>
<h3><a name="ACL-Specification"></a>Specification</h3>

<p>&nbsp;Notes on file formats</p>

<ul>
	<li>A line starting with the character '#' will be considered a comment, and are ignored.</li>
	<li>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.</li>
	<li>Empty lines ("") and lines that contain only whitespace (any combination of ' ',
'\f', '\n', '\r', '\t', '\v') are ignored.</li>
	<li>All tokens are case sensitive. "name1" != "Name1" and "create" != "CREATE".</li>
	<li>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.
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
# 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
</pre>
</div></div></li>
	<li>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.</li>
	<li>All acl rules are limited to a single line.</li>
	<li>Rules are interpreted from the top of the file down until the name match is obtained;
at which point processing stops.</li>
	<li>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".</li>
	<li>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.</li>
	<li>Property names, Usernames and group names may contain only <b>a-z , A-Z ,
0-9 , '-' , '_' &amp; '.'</b>.</li>
	<li>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.</li>
	<li>ACL rules must have the following tokens in order on a single line:
	<ul>
		<li>The string literal "acl";</li>
		<li>The permission;</li>
		<li>The name of a single group or individual or the keyword "all";</li>
		<li>The name of an action or the keyword "all";</li>
		<li>Optionally, a single object name or the keyword "all";</li>
		<li>If the object is present, then optionally one or more property name-value pair(s)
(in the form property=value).</li>
	</ul>
	</li>
</ul>



<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
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;|<span class="code-quote">"all"</span>}
{action|<span class="code-quote">"all"</span>} [object|<span class="code-quote">"all"</span>]
[property=&lt;property-value&gt;]
</pre>
</div></div>

<h3><a name="ACL-Validation"></a>Validation</h3>

<p>The new ACL file format needs to perform validation on the acl rules. The validation
should be performed depending on the set value:</p>

<p>strict-acl-validation=<a href="/confluence/pages/createpage.action?spaceKey=qpid&amp;title=warn*&amp;linkCreation=true&amp;fromPageId=91817"
title="error|fatal" class="createlink">none</a><br/>
The default setting should be 'warn'</p>

<p>On validation of this acl the following checks would be expected:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
acl allow client publish routingkey=exampleQueue exchange=amq.direct
</pre>
</div></div>

<ol>
	<li>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.</li>
	<li>There is an exchange called 'amq.direct'</li>
	<li>There is a queue bound to 'exampleQueue' on 'amq.direct'</li>
</ol>


<p>Each of these checks that fail will result in a log statement being generated.</p>

<p>In the case of a fatal logging the full file will be validated before the broker
shuts down.</p>

<h3><a name="ACL-Examplefile%3A"></a>Example file:</h3>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">

# 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=<span class="code-keyword">false</span>
acl allow publisher create queue name=RequestQueue
acl allow consumer consume queue durable=<span class="code-keyword">true</span>
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 (<span class="code-keyword">default</span>) rule
acl deny all all
</pre>
</div></div>


<p><a name="ACL-design"></a></p>
<h2><a name="ACL-DesignDocumentation"></a>Design Documentation</h2>
<h3><a name="ACL-MappingofACLtrapstoactionandtype"></a>Mapping of ACL traps
to action and type</h3>

<p>The C++ broker maps the ACL traps in the follow way for AMQP 0-10:<br/>
The Java broker currently only performs ACLs on the AMQP connection not on management functions:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Object</th>
<th class='confluenceTh'> Action</th>
<th class='confluenceTh'> Properties</th>
<th class='confluenceTh'> Trap C++</th>
<th class='confluenceTh'> Trap Java </th>
</tr>
<tr>
<td class='confluenceTd'>Exchange</td>
<td class='confluenceTd'>Create </td>
<td class='confluenceTd'> name type alternate passive durable </td>
<td class='confluenceTd'> ExchangeHandlerImpl::declare </td>
<td class='confluenceTd'> ExchangeDeclareHandler </td>
</tr>
<tr>
<td class='confluenceTd'>Exchange</td>
<td class='confluenceTd'>Delete </td>
<td class='confluenceTd'> name </td>
<td class='confluenceTd'> ExchangeHandlerImpl::delete </td>
<td class='confluenceTd'> ExchangeDeleteHandler </td>
</tr>
<tr>
<td class='confluenceTd'>Exchange</td>
<td class='confluenceTd'>Access </td>
<td class='confluenceTd'> name </td>
<td class='confluenceTd'> ExchangeHandlerImpl::query </td>
<td class='confluenceTd'><ul class="alternate" type="square">
	<li></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'>Exchange</td>
<td class='confluenceTd'>Bind   </td>
<td class='confluenceTd'> name routingkey queuename owner </td>
<td class='confluenceTd'> ExchangeHandlerImpl::bind </td>
<td class='confluenceTd'> QueueBindHandler </td>
</tr>
<tr>
<td class='confluenceTd'>Exchange</td>
<td class='confluenceTd'>Unbind </td>
<td class='confluenceTd'> name routingkey </td>
<td class='confluenceTd'>ExchangeHandlerImpl::unbind </td>
<td class='confluenceTd'> ExchangeUnbindHandler </td>
</tr>
<tr>
<td class='confluenceTd'>Exchange</td>
<td class='confluenceTd'>Access </td>
<td class='confluenceTd'> name queuename routingkey </td>
<td class='confluenceTd'>ExchangeHandlerImpl::bound </td>
<td class='confluenceTd'><ul class="alternate" type="square">
	<li></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'>Exchange</td>
<td class='confluenceTd'>Publish</td>
<td class='confluenceTd'> name routingKey </td>
<td class='confluenceTd'>SemanticState::route </td>
<td class='confluenceTd'> BasicPublishMethodHandler </td>
</tr>
<tr>
<td class='confluenceTd'>Queue   </td>
<td class='confluenceTd'>Access </td>
<td class='confluenceTd'> name </td>
<td class='confluenceTd'>QueueHandlerImpl::query </td>
<td class='confluenceTd'><ul class="alternate" type="square">
	<li></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'>Queue   </td>
<td class='confluenceTd'>Create </td>
<td class='confluenceTd'> name alternate passive durable exclusive autodelete </td>
<td class='confluenceTd'>QueueHandlerImpl::declare </td>
<td class='confluenceTd'> QueueDeclareHandler </td>
</tr>
<tr>
<td class='confluenceTd'>Queue   </td>
<td class='confluenceTd'>Purge  </td>
<td class='confluenceTd'> name </td>
<td class='confluenceTd'>QueueHandlerImpl::purge </td>
<td class='confluenceTd'> QueuePurgeHandler </td>
</tr>
<tr>
<td class='confluenceTd'>Queue   </td>
<td class='confluenceTd'>Purge  </td>
<td class='confluenceTd'> name </td>
<td class='confluenceTd'>Management::Queue::purge </td>
<td class='confluenceTd'><ul class="alternate" type="square">
	<li></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'>Queue   </td>
<td class='confluenceTd'>Delete </td>
<td class='confluenceTd'> name </td>
<td class='confluenceTd'>QueueHandlerImpl::delete </td>
<td class='confluenceTd'> QueueDeleteHandler </td>
</tr>
<tr>
<td class='confluenceTd'>Queue   </td>
<td class='confluenceTd'>Consume </td>
<td class='confluenceTd'> name (possibly add in future?) </td>
<td class='confluenceTd'>MessageHandlerImpl::subscribe </td>
<td class='confluenceTd'> BasicConsumeMethodHandler<br class="atl-forced-newline"
/> BasicGetMethodHandler </td>
</tr>
<tr>
<td class='confluenceTd'>&lt;Object&gt;</td>
<td class='confluenceTd'>Update </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>ManagementProperty::set </td>
<td class='confluenceTd'><ul class="alternate" type="square">
	<li></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'>&lt;Object&gt;</td>
<td class='confluenceTd'>Access </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>ManagementProperty::read </td>
<td class='confluenceTd'><ul class="alternate" type="square">
	<li></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'>Link    </td>
<td class='confluenceTd'>Create </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Management::connect </td>
<td class='confluenceTd'><ul class="alternate" type="square">
	<li></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'>Route   </td>
<td class='confluenceTd'>Create </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Management:: -<del>createFederationRoute</del>-
</td>
<td class='confluenceTd'><ul class="alternate" type="square">
	<li></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'>Route   </td>
<td class='confluenceTd'>Delete </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>Management:: -<del>deleteFederationRoute</del>-
</td>
<td class='confluenceTd'><ul class="alternate" type="square">
	<li></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'>Virtualhost</td>
<td class='confluenceTd'> Access </td>
<td class='confluenceTd'> name </td>
<td class='confluenceTd'> TBD </td>
<td class='confluenceTd'> ConnectionOpenMethodHandler </td>
</tr>
</tbody></table>
</div>



<p>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'. </p>

<p>for example, if the mgnt method 'joinCluster' was not mapped in schema it will be
mapped in ACL file as follows</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Object </th>
<th class='confluenceTh'> Action </th>
<th class='confluenceTh'> Property</th>
</tr>
<tr>
<td class='confluenceTd'>Broker</td>
<td class='confluenceTd'>Update</td>
<td class='confluenceTd'> name=joinCluster</td>
</tr>
</tbody></table>
</div>





<p><a name="ACL-userguide"></a></p>
<h2><a name="ACL-v2ACLUserGuide"></a>v2 ACL User Guide</h2>


<h3><a name="ACL-WritingGood%2FFastACL"></a>Writing Good/Fast ACL</h3>


<p>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.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
allow peter@QPID create queue name=tmp &lt;-- dead rule!!
allow peter@QPID create queue
deny all all
</pre>
</div></div>

<p>By default files end with </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
deny all all
</pre>
</div></div>

<p>the mode of the ACL engine can be swapped to be allow based by putting the following
at the end of the file</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
allow all all
</pre>
</div></div>

<p>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.</p>

<h3><a name="ACL-GettingACLtoLog"></a>Getting ACL to Log</h3>

<p>In order to get log messages from ACL actions use allow-log and deny-log for example</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
allow-log john@QPID all all
deny-log guest@QPID all all
</pre>
</div></div>

<h3><a name="ACL-UserId%2FdomainsrunningwithCbroker"></a>User Id / domains
running with C++ broker</h3>

<p>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)</p>

<p>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'.</p>

<p>To load the ACL module use, load the acl module cmd line or via the config file</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
./src/qpidd --load-module src/.libs/acl.so
</pre>
</div></div>

<p>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.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
ACL Options:
  --acl-file FILE       The policy file to load from, loaded from data dir
</pre>
</div></div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="http://cwiki.apache.org/confluence/display/qpid/ACL">View Online</a>
        |
        <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=91817&revisedVersion=54&originalVersion=53">View
Changes</a>
                |
        <a href="http://cwiki.apache.org/confluence/display/qpid/ACL?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org


Mime
View raw message