Author: chug
Date: Wed Sep 12 21:36:40 2012
New Revision: 1384137
URL: http://svn.apache.org/viewvc?rev=1384137&view=rev
Log:
NO-JIRA Add design doc describing C++ Broker Acl additions.
Added:
qpid/trunk/qpid/cpp/design_docs/broker-acl-work.txt
Added: qpid/trunk/qpid/cpp/design_docs/broker-acl-work.txt
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/design_docs/broker-acl-work.txt?rev=1384137&view=auto
==============================================================================
--- qpid/trunk/qpid/cpp/design_docs/broker-acl-work.txt (added)
+++ qpid/trunk/qpid/cpp/design_docs/broker-acl-work.txt Wed Sep 12 21:36:40 2012
@@ -0,0 +1,152 @@
+-*-org-*-
+# 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.
+
+The broker is accumulating ACL features and additions. This document describes
the features and some of the strategies and decisions made along the way.
+
+These changes are not coordinated with the Java Broker.
+
+Queue Limit Property Settings
+=============================
+
+Customer Goal: Prevent users from making queues too small or too big
+in memory and on disk.
+
+* Add property limit settings to CREATE QUEUE Acl rules.
+
+User Option Acl Limit Property Units
+--------------- ---------------------- ---------------
+qpid.max_size queuemaxsizelowerlimit bytes
+ queuemaxsizeupperlimit bytes
+qpid.max_count queuemaxcountlowerlimit messages
+ queuemaxcountupperlimit messages
+qpid.file_size filemaxsizelowerlimit pages (64Kb per page)
+ filemaxsizeupperlimit pages (64Kb per page)
+qpid.file_count filemaxcountlowerlimit files
+ filemaxcountupperlimit files
+
+
+* Change rule match behavior to accomodate limit settings
+
+** Normal properties upon seeing a mismatch cause the Acl rule processor to go
on to the next rule. Property limit settings do not cause a rule mismatch.
+** When property limit checks are violated the effect is to demote an allow
rule into a deny rule. Property limit checks are ignored in deny rules.
+
+Routingkey Wildcard Match
+=========================
+
+Customer Goal: Allow users to bind, unbind, access, and publish with wildcards
in the routingkey property. A single trailing * wildcard match is insufficient.
+
+* Acl rule processing uses the broker's topic exchange match logic when
matching any exchange rule with a "routingkey" property.
+
+* Acl rule writers get to use the same rich matching logic that the broker
uses when, for instance, it decides which topic exchange binding keys satisfy
an incoming message's routing key.
+
+User Name and Domain Name Symbol Substitution
+=============================================
+
+Customer Goal: Create rules that allow users to access resources only when the
user's name is embedded in the resource name.
+
+* The Acl rule processor defines keywords which are substituted with the
user's user and domain name.
+
+* User name substitution is allowed in the Acl file anywhere that text is
supplied for a property value.
+
+In the following table an authenticated user [email protected] has his
substitution keywords expanded.
+
+| Keyword | Expansion |
+|---------------+--------------|
+| ${userdomain} | bob_QPID_COM |
+| ${user} | bob |
+| ${domain} | QPID_COM |
+
+* User names are normalized by changing asterisk '*' and period '.' to
underscores. This allows substitution to work with routingkey specfications.
+
+* The Acl processor matches ${userdomain} before matching either ${user} or
${domain}. Rules that specify ${user}_${domain} will never match.
+
+Resource Quotas
+===============
+
+The Acl module provides broker command line switches to limit users' access to
queues and connections.
+
+| Command Line Option | Specified Quota | Default |
+|------------------------------+--------------------------+---------|
+| --max-connections-per-user N | connections by user name | 0 |
+| --max-connections-per-IP N | connections by host name | 0 |
+| --max-queues-per-user N | queues by user name | 0 |
+
+* Allowed values for N are 0..65535
+
+* An option value of zero (0) disables that limit check.
+
+* Connections per-user are counted using the authenticated user name. The user
may be logged in from any location but resource counts are aggregated under the
user's name.
+
+* Connections per-IP are identified by the
<broker-ip><broker-port>-<client-ip><client-port> tuple. This is the same
string used by broker management to index connections.
+
+** With this scheme hosts may be identified by several names such as
localhost, 127.0.0.1, or ::1. A separate counted set of connections is allowed
for each name.
+
+** Connections per-ip are counted regardless of the credentials provided with
each connection. A user may be allowed 20 connections but if the per-ip limit
is 5 then that user may connect from any single host only five times.
+
+Acl Management Interface
+========================
+
+* Acl Lookup Query Methods
+
+The Acl module provides two QMF management methods that allow users to query
the Acl authorization interface.
+
+ Method: Lookup
+ Argument Type Direction Unit Description
+ ========================================================
+ userId long-string I
+ action long-string I
+ object long-string I
+ objectName long-string I
+ propertyMap field-table I
+ result long-string O
+
+ Method: LookupPublish
+ Argument Type Direction Unit Description
+ =========================================================
+ userId long-string I
+ exchangeName long-string I
+ routingKey long-string I
+ result long-string O
+
+The Lookup method is a general query for any action, object, and set of
properties.
+The LookupPublish method is the optimized, per-message fastpath query.
+
+In both methods the result is one of: allow, deny, allow-log, or deny-log.
+
+Example:
+
+The upstream Jira https://issues.apache.org/jira/browse/QPID-3918 has several
attachment files that demonstrate how to use the query feature.
+
+ acl-test-01.rules.acl is the Acl file to run in the qpidd broker.
+ acl-test-01.py is the test script that queries the Acl.
+ acl-test-01.log is what the console prints when the test script runs.
+
+The script performs 355 queries using the Acl Lookup query methods.
+
+* Management Properties and Statistics
+
+The following properties and statistics have been added to reflect command
line settings in effect and Acl quota denial activity.
+
+Element Type Access Unit Notes Description
+==================================================================================================
+maxConnections uint16 ReadOnly Maximum
allowed connections
+maxConnectionsPerIp uint16 ReadOnly Maximum
allowed connections
+maxConnectionsPerUser uint16 ReadOnly Maximum
allowed connections
+maxQueuesPerUser uint16 ReadOnly Maximum
allowed queues
+connectionDenyCount uint64 Number of
connections denied
+queueQuotaDenyCount uint64 Number of
queue creations denied
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
