diff options
Diffstat (limited to 'qpid/cpp/design_docs/broker-acl-work.txt')
| -rw-r--r-- | qpid/cpp/design_docs/broker-acl-work.txt | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/qpid/cpp/design_docs/broker-acl-work.txt b/qpid/cpp/design_docs/broker-acl-work.txt new file mode 100644 index 0000000000..e587dc5198 --- /dev/null +++ b/qpid/cpp/design_docs/broker-acl-work.txt @@ -0,0 +1,156 @@ +-*-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 +qpid.max_pages_loaded pageslowerlimit pages + pagesupperlimit pages +qpid.page_factor pagefactorlowerlimit integer (multiple of the platform-defined page size) + pagefactorlowerlimit integer (multiple of the platform-defined page size) + + +* 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 bob@QPID.COM 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 |