-*-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 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