Menu Search

1.5. Security

This chapter describes how authentication, rule-based authorization, encryption, and digital signing can be accomplished using Qpid. Authentication is the process of verifying the identity of a user; in Qpid, this is done using the SASL framework. Rule-based authorization is a mechanism for specifying the actions that each user is allowed to perform; in Qpid, this is done using an Access Control List (ACL) that is part of the Qpid broker. Encryption is used to ensure that data is not transferred in a plain-text format that could be intercepted and read. Digital signatures provide proof that a given message was sent by a known sender. Encryption and signing are done using SSL (they can also be done using SASL, but SSL provides stronger encryption).

1.5.1. User Authentication

AMQP uses Simple Authentication and Security Layer (SASL) to authenticate client connections to the broker. SASL is a framework that supports a variety of authentication methods. For secure applications, we suggest CRAM-MD5, DIGEST-MD5, or GSSAPI. The ANONYMOUS method is not secure. The PLAIN method is secure only when used together with SSL.

Both the Qpid broker and Qpid clients use the Cyrus SASL library, a full-featured authentication framework, which offers many configuration options. This section shows how to configure users for authentication with SASL, which is sufficient when using SASL PLAIN. If you are not using SSL, you should configure SASL to use CRAM-MD5, DIGEST-MD5, or GSSAPI (which provides Kerberos authentication). For information on configuring these and other options in SASL, see the Cyrus SASL documentation.

Important

The SASL PLAIN method sends passwords in cleartext, and is vulnerable to man-in-the-middle attacks unless SSL (Secure Socket Layer) is also used (see Section 1.5.4, “Encryption using SSL”).

If you are not using SSL, we recommend that you disable PLAIN authentication in the broker.

The Qpid broker uses the auth yes|no option to determine whether to use SASL authentication. Turn on authentication by setting auth to yes in /etc/qpidd.conf:

# /etc/qpidd.conf
#
# Set auth to 'yes' or 'no'

auth=yes

1.5.1.1. Configuring SASL

On Linux systems, the SASL configuration file is generally found in /etc/sasl2/qpidd.conf or /usr/lib/sasl2/qpidd.conf.

The SASL database contains user names and passwords for SASL. In SASL, a user may be associated with a realm. The Qpid broker authenticates users in the QPID realm by default, but it can be set to a different realm using the realm option:

# /etc/qpidd.conf
#
# Set the SASL realm using 'realm='

auth=yes
realm=QPID

The SASL database is installed at /var/lib/qpidd/qpidd.sasldb; initially, it has one user named guest in the QPID realm, and the password for this user is guest.

Note

The user database is readable only by the qpidd user. When run as a daemon, Qpid always runs as the qpidd user. If you start the broker from a user other than the qpidd user, you will need to either reconfigure SASL or turn authentication off.

Important

The SASL database stores user names and passwords in plain text. If it is compromised so are all of the passwords that it stores. This is the reason that the qpidd user is the only user that can read the database. If you modify permissions, be careful not to expose the SASL database.

Add new users to the database by using the saslpasswd2 command, which specifies a realm and a user ID. A user ID takes the form user-id@domain..

# saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u realm new_user_name

To list the users in the SASL database, use sasldblistusers2:

# sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb

If you are using PLAIN authentication, users who are in the database can now connect with their user name and password. This is secure only if you are using SSL. If you are using a more secure form of authentication, please consult your SASL documentation for information on configuring the options you need.

1.5.1.2. Kerberos

Both the Qpid broker and Qpid users are 'principals' of the Kerberos server, which means that they are both clients of the Kerberos authentication services.

To use Kerberos, both the Qpid broker and each Qpid user must be authenticated on the Kerberos server:

  1. Install the Kerberos workstation software and Cyrus SASL GSSAPI on each machine that runs a qpidd broker or a qpidd messaging client:

    $ sudo yum install cyrus-sasl-gssapi krb5-workstation
  2. Make sure that the Qpid broker is registered in the Kerberos database.

    Traditionally, a Kerberos principal is divided into three parts: the primary, the instance, and the realm. A typical Kerberos V5 has the format primary/instance@REALM. For a Qpid broker, the primary is qpidd, the instance is the fully qualified domain name, which you can obtain using hostname --fqdn, and the REALM is the Kerberos domain realm. By default, this realm is QPID, but a different realm can be specified in qpid.conf, e.g.:

    realm=EXAMPLE.COM

    For instance, if the fully qualified domain name is dublduck.example.com and the Kerberos domain realm is EXAMPLE.COM, then the principal name is qpidd/dublduck.example.com@EXAMPLE.COM.

    The following script creates a principal for qpidd:

    FDQN=`hostname --fqdn`
    REALM="EXAMPLE.COM"
    kadmin -r $REALM  -q "addprinc -randkey -clearpolicy qpidd/$FQDN"
    

    Now create a Kerberos keytab file for the Qpid broker. The Qpid broker must have read access to the keytab file. The following script creates a keytab file and allows the broker read access:

    QPIDD_GROUP="qpidd"
    kadmin -r $REALM  -q "ktadd -k /etc/qpidd.keytab qpidd/$FQDN@$REALM"
    chmod g+r /etc/qpidd.keytab
    chgrp $QPIDD_GROUP /etc/qpidd.keytab
    

    The default location for the keytab file is /etc/krb5.keytab. If a different keytab file is used, the KRB5_KTNAME environment variable must contain the name of the file, e.g.:

    export KRB5_KTNAME=/etc/qpidd.keytab
    

    If this is correctly configured, you can now enable kerberos support on the Qpid broker by setting the auth and realm options in /etc/qpidd.conf:

    # /etc/qpidd.conf
    auth=yes
    realm=EXAMPLE.COM
    

    Restart the broker to activate these settings.

  3. Make sure that each Qpid user is registered in the Kerberos database, and that Kerberos is correctly configured on the client machine. The Qpid user is the account from which a Qpid messaging client is run. If it is correctly configured, the following command should succeed:

    $ kinit user@REALM.COM

Java JMS clients require a few additional steps.

  1. The Java JVM must be run with the following arguments:

    -Djavax.security.auth.useSubjectCredsOnly=false

    Forces the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the "subject" that owns the current thread.

    -Djava.security.auth.login.config=myjas.conf

    Specifies the jass configuration file. Here is a sample JASS configuration file:

    com.sun.security.jgss.initiate {
        com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
    };
    
    -Dsun.security.krb5.debug=true

    Enables detailed debug info for troubleshooting

  2. The client's Connection URL must specify the following Kerberos-specific broker properties:

    • sasl_mechs must be set to GSSAPI.

    • sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd/

    • sasl_server must be set to the host for the SASL server, e.g. sasl.com.

    Here is a sample connection URL for a Kerberos connection:

    amqp://guest@clientid/testpath?brokerlist='tcp://localhost:5672?sasl_mechs='GSSAPI'&sasl_protocol='qpidd'&sasl_server='<server-host-name>''

1.5.2. Authorization

In Qpid, Authorization specifies which actions can be performed by each authenticated user using an Access Control List (ACL).

Use the --acl-file command to load the access control list. The filename should have a .acl extension:

    $ qpidd --acl-file ./aclfilename.acl

Each line in an ACL file grants or denies specific rights to a user. If the last line in an ACL file is acl deny all all, the ACL uses deny mode, and only those rights that are explicitly allowed are granted:

    acl allow rajith@QPID all all
    acl deny all all

On this server, rajith@QPID can perform any action, but nobody else can. Deny mode is the default, so the previous example is equivalent to the following ACL file:

    acl allow rajith@QPID all all

Alternatively the ACL file may use allow mode by placing:

    acl allow all all

as the final line in the ACL file. In allow mode all actions by all users are allowed unless otherwise denied by specific ACL rules. The ACL rule which selects deny mode or allow mode must be the last line in the ACL rule file.

ACL syntax allows fine-grained access rights for specific actions:

    acl allow carlt@QPID create exchange name=carl.*
    acl allow fred@QPID create all
    acl allow all consume queue
    acl allow all bind exchange
    acl deny all all

An ACL file can define user groups, and assign permissions to them:

    group admin ted@QPID martin@QPID
    acl allow admin create all
    acl deny all all

Performance Note: Most ACL queries are performed infrequently. The overhead associated with ACL passing an allow or deny decision on the creation of a queue is negligible compared to actually creating and using the queue. One notable exception is the publish exchange query. ACL files with no publish exchange rules are noted and the broker short circuits the logic associated with the per-messsage publish exchange ACL query. However, if an ACL file has any publish exchange rules then the broker is required to perform a publish exchange query for each message published. Users with performance critical applications are encouraged to structure exchanges, queues, and bindings so that the publish exchange ACL rules are unnecessary.

1.5.2.1. ACL Syntax

ACL rules must be on a single line and follow this syntax:

    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 = [queue | exchange | broker | link | method]
    property = [name | durable | owner | routingkey | 
                autodelete | exclusive |type | 
		alternate | queuename | 
		schemapackage | schemaclass | 
		queuemaxsizelowerlimit  | 
		queuemaxsizeupperlimit  |
                queuemaxcountlowerlimit | 
		queuemaxcountupperlimit |
                filemaxsizelowerlimit   | 
		filemaxsizeupperlimit   |
                filemaxcountlowerlimit  | 
		filemaxcountupperlimit ]
    
    acl permission {<group-name>|<user-name>|"all"} {action|"all"} [object|"all" 
                [property=<property-value> ...]]

ACL rules can also include a single object name (or the keyword all) and one or more property name value pairs in the form property=value

The following tables show the possible values for permission, action, object, and property in an ACL rules file.

Table 1.4. ACL Rules: permission

allow

Allow the action

allow-log

Allow the action and log the action in the event log

deny

Deny the action

deny-log

Deny the action and log the action in the event log


Table 1.5. ACL Rules:action

consume

Applied when subscriptions are created

publish

Applied on a per message basis to verify that the user has rights to publish to the given exchange with the given routingkey.

create

Applied when an object is created, such as bindings, queues, exchanges, links

access

Applied when an object is read or accessed

bind

Applied when objects are bound together

unbind

Applied when objects are unbound

delete

Applied when objects are deleted

purge

Similar to delete but the action is performed on more than one object

update

Applied when an object is updated


Table 1.6. ACL Rules:object

queue

A queue

exchange

An exchange

broker

The broker

link

A federation or inter-broker link

method

Management or agent or broker method


Table 1.7. ACL Rules:property

PropertyTypeDescriptionUsage
name StringObject name, such as a queue name or exchange name. 
durable BooleanIndicates the object is durableCREATE QUEUE, CREATE EXCHANGE, ACCESS QUEUE, ACCESS EXCHANGE
routingkey StringSpecifies routing keyBIND EXCHANGE, UNBIND EXCHANGE, ACCESS EXCHANGE, PUBLISH EXCHANGE
autodelete BooleanIndicates whether or not the object gets deleted when the connection is closedCREATE QUEUE, ACCESS QUEUE
exclusive BooleanIndicates the presence of an exclusive flagCREATE QUEUE, ACCESS QUEUE
type StringType of exchange, such as topic, fanout, or xmlCREATE EXCHANGE, ACCESS EXCHANGE
alternate StringName of the alternate exchangeCREATE EXCHANGE, CREATE QUEUE, ACCESS EXCHANGE, ACCESS QUEUE
queuename StringName of the queueACCESS EXCHANGE, BIND EXCHANGE, UNBIND EXCHANGE
schemapackage StringQMF schema package nameACCESS METHOD
schemaclass StringQMF schema class nameACCESS METHOD
queuemaxsizelowerlimit IntegerMinimum value for queue.max_size (memory bytes)CREATE QUEUE, ACCESS QUEUE
queuemaxsizeupperlimit IntegerMaximum value for queue.max_size (memory bytes)CREATE QUEUE, ACCESS QUEUE
queuemaxcountlowerlimit IntegerMinimum value for queue.max_count (messages)CREATE QUEUE, ACCESS QUEUE
queuemaxcountupperlimit IntegerMaximum value for queue.max_count (messages)CREATE QUEUE, ACCESS QUEUE
filemaxsizelowerlimit IntegerMinimum value for file.max_size (64kb pages)CREATE QUEUE, ACCESS QUEUE
filemaxsizeupperlimit IntegerMaximum value for file.max_size (64kb pages)CREATE QUEUE, ACCESS QUEUE
filemaxcountlowerlimit IntegerMinimum value for file.max_count (files)CREATE QUEUE, ACCESS QUEUE
filemaxcountupperlimit IntegerMaximum value for file.max_count (files)CREATE QUEUE, ACCESS QUEUE

ACL Action-Object-Property Tuples

Not every ACL action is applicable to every ACL object. Furthermore, not every property may be specified for every action-object pair. The following table enumerates which action and object pairs are allowed. The table also lists which optional ACL properties are allowed to qualify action-object pairs.

The access action is called with different argument lists for the exchange and queue objects. A separate column shows the AMQP 0.10 method that the Access ACL rule is satisfying. Write separate rules with the additional arguments for the declare and bind methods and include these rules in the ACL file before the rules for the query method.

Table 1.8. ACL Properties Allowed for each Action and Object

ActionObjectPropertiesMethod
accessbroker  
accessexchangename type alternate durabledeclare
accessexchangename queuename routingkeybound
accessexchangenamequery
accessmethodname schemapackage schemaclass 
accessqueuename alternate durable exclusive autodelete policy queuemaxsizelowerlimit queuemaxsizeupperlimit queuemaxcountlowerlimit queuemaxcountupperlimit filemaxsizelowerlimit filemaxsizeupperlimit filemaxcountlowerlimit filemaxcountupperlimitdeclare
accessqueuenamequery
bindexchangename queuename routingkey 
consumequeuename 
createexchangename type alternate durable 
createlinkname 
createqueuename alternate durable exclusive autodelete policy queuemaxsizelowerlimit queuemaxsizeupperlimit queuemaxcountlowerlimit queuemaxcountupperlimit filemaxsizelowerlimit filemaxsizeupperlimit filemaxcountlowerlimit filemaxcountupperlimit 
deleteexchangename 
deletequeuename 
publishexchangename routingkey 
purgequeuename 
unbindexchangename queuename routingkey 
updatebroker  

1.5.2.2. ACL Syntactic Conventions

Comments

  • A line starting with the # character is considered a comment and is ignored.

  • Embedded comments and trailing comments are not allowed. The # is commonly found in routing keys and other AMQP literals which occur naturally in ACL rule specifications.

White Space
  • Empty lines and lines that contain only whitespace (' ', '\f', '\n', '\r', '\t', '\v') are ignored.

  • Additional whitespace between and after tokens is allowed.

  • Group and Acl definitions must start with group and acl respectively and with no preceding whitespace.

Character Set
  • ACL files use 7-bit ASCII characters only

  • Group names may contain only

    • [a-z]
    • [A-Z]
    • [0-9]
    • '-' hyphen
    • '_' underscore

  • Individual user names may contain only

    • [a-z]
    • [A-Z]
    • [0-9]
    • '-' hyphen
    • '_' underscore
    • '.' period
    • '@' ampersand
    • '/' slash

Case Sensitivity
  • All tokens are case sensitive. name1 is not the same as Name1 and create is not the same as CREATE.

Line Continuation
  • Group lists can be extended to the following line by terminating the line with the '\' character. No other ACL file lines may be continued.

  • Group specification lines may be continued only after the group name or any of the user names included in the group. See example below.

  • Lines consisting solely of a '\' character are not permitted.

  • The '\' continuation character is recognized only if it is the last character in the line. Any characters after the '\' are not permitted.

    #
    # 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 line
    #
    group group4 name9 \
                       \
                 name10
Line Length
  • ACL file lines are limited to 1024 characters.

ACL File Keywords
ACL reserves several words for convenience and for context sensitive substitution.
The all Keyword
The keyword all is reserved. It may be used in ACL rules to match all individuals and groups, all actions, or all objects.
  • acl allow all create queue
  • acl allow bob@QPID all queue
  • acl allow bob@QPID create all
User Name and Domain Name Keywords

In the C++ Broker 0.20 a simple set of user name and domain name substitution variable keyword tokens is defined. This provides administrators with an easy way to describe private or shared resources.

Symbol substitution is allowed in the ACL file anywhere that text is supplied for a property value.

In the following table an authenticated user named bob.user@QPID.COM has his substitution keywords expanded.

Table 1.9. ACL User Name and Domain Name Substitution Keywords

KeywordExpansion
${userdomain} bob_user_QPID_COM
${user} bob_user
${domain} QPID_COM


  • The original user name has the period “.” and ampersand “@” characters translated into underscore “_”. This allows substitution to work when the substitution keyword is used in a routingkey in the Acl file.
  • The Acl processing matches ${userdomain} before matching either ${user} or ${domain}. Rules that specify the combination ${user}_${domain} will never match.

  # Example:
  # 
  # Administrators can set up Acl rule files that allow every user to create a
  # private exchange, a private queue, and a private binding between them. 
  # In this example the users are also allowed to create private backup exchanges, 
  # queues and bindings. This effectively provides limits to user's exchange, 
  # queue, and binding creation and guarantees that each user gets exclusive 
  # access to these resources.
  # 
  #
  # Create primary queue and exchange:
  #
  acl allow all create  queue    name=$\{user}-work alternate=$\{user}-work2
  acl deny  all create  queue    name=$\{user}-work alternate=*
  acl allow all create  queue    name=$\{user}-work
  acl allow all create  exchange name=$\{user}-work alternate=$\{user}-work2
  acl deny  all create  exchange name=$\{user}-work alternate=*
  acl allow all create  exchange name=$\{user}-work
  #
  # Create backup queue and exchange
  #
  acl deny  all create  queue    name=$\{user}-work2 alternate=*
  acl allow all create  queue    name=$\{user}-work2
  acl deny  all create  exchange name=$\{user}-work2 alternate=*
  acl allow all create  exchange name=$\{user}-work2
  #
  # Bind/unbind primary exchange
  #
  acl allow all bind   exchange name=$\{user}-work routingkey=$\{user} queuename=$\{user}-work
  acl allow all unbind exchange name=$\{user}-work routingkey=$\{user} queuename=$\{user}-work
  #
  # Bind/unbind backup exchange
  #
  acl allow all bind   exchange name=$\{user}-work2 routingkey=$\{user} queuename=$\{user}-work2
  acl allow all unbind exchange name=$\{user}-work2 routingkey=$\{user} queuename=$\{user}-work2
  #
  # Access primary exchange
  #
  acl allow all access exchange name=$\{user}-work routingkey=$\{user} queuename=$\{user}-work
  #
  # Access backup exchange
  #
  acl allow all access exchange name=$\{user}-work2 routingkey=$\{user} queuename=$\{user}-work2
  #
  # Publish primary exchange
  #
  acl allow all publish exchange name=$\{user}-work routingkey=$\{user}
  #
  # Publish backup exchange
  #
  acl allow all publish exchange name=$\{user}-work2 routingkey=$\{user}
  #
  # deny mode
  #
  acl deny all all
Wildcards
ACL privides two types of wildcard matching to provide flexibility in writing rules.
Property Value Wildcard

Text specifying a property value may end with a single trailing * character. This is a simple wildcard match indicating that strings which match up to that point are matches for the ACL property rule. An ACL rule such as

    acl allow bob@QPID create queue name=bob*

allow user bob@QPID to create queues named bob1, bob2, bobQueue3, and so on.

Topic Routing Key Wildcard

In the C++ Broker 0.20 the logic governing the ACL Match has changed for each ACL rule that contains a routingkey property. The routingkey property is matched according to Topic Exchange match logic the broker uses when it distributes messages published to a topic exchange.

Routing keys are hierarchical where each level is separated by a period:

  • weather.usa
  • weather.europe.germany
  • weather.europe.germany.berlin
  • company.engineering.repository

Within the routing key hierarchy two wildcard characters are defined.

  • * matches one field
  • # matches zero or more fields

Suppose an ACL rule file is:

    acl allow-log uHash1@COMPANY publish exchange name=X routingkey=a.#.b
    acl deny all all
			      

When user uHash1@COMPANY attempts to publish to exchange X the ACL will return these results:

Table 1.10. Topic Exchange Wildcard Match Examples

routingkey in publish to exchange Xresult
a.b allow-log
a.x.b allow-log
a.x.y.zz.b allow-log
a.b. deny
q.x.b deny


1.5.2.3. ACL Rule Matching

The minimum matching criteria for ACL rules are:

  • An actor (individually named or group member)
  • An action
  • An object

If a rule does not match the minimum criteria then that rule does not control the ACL allow or deny decision.

ACL rules optionally specify object names and property name=value pairs. If an ACL rule specifies an object name or property values than all of them must match to cause the rule to match.

The following illustration shows how ACL rules are processed to find matching rules.

    # Example of rule matching
    #
    # Using this ACL file content:
    
    (1)  acl deny bob create exchange name=test durable=true passive=true
    (2)  acl deny bob create exchange name=myEx type=direct
    (3)  acl allow all all
    
    #
    # Lookup 1. id:bob action:create objectType:exchange name=test 
    #           {durable=false passive=false type=direct alternate=}
    #
    # ACL Match Processing:
    #  1. Rule 1 passes minimum criteria with user bob, action create, 
    #     and object exchange.
    #  2. Rule 1 matches name=test.
    #  3. Rule 1 does not match the rule's durable=true with the requested 
    #     lookup of durable=false.
    #  4. Rule 1 does not control the decision and processing continues 
    #     to Rule 2.
    #  5. Rule 2 passes minimum criteria with user bob, action create, 
    #     and object exchange.
    #  6. Rule 2 does not match the rule's name=myEx with the requested 
    #     lookup of name=test.
    #  7. Rule 2 does not control the decision and processing continues 
    #     to Rule 3.
    #  8. Rule 3 matches everything and the decision is 'allow'.
    #
    # Lookup 2. id:bob action:create objectType:exchange name=myEx 
    #           {durable=true passive=true type=direct alternate=}
    #
    # ACL Match Processing:
    #  1. Rule 1 passes minimum criteria with user bob, action create, 
    #     and object exchange.
    #  2. Rule 1 does not match the rule's name=test with the requested 
    #     lookup of name=myEx.
    #  3. Rule 1 does not control the decision and processing continues
    #     to Rule 2.
    #  4. Rule 2 passes minimum criteria with user bob, action create, 
    #     and object exchange.
    #  5. Rule 2 matches name=myEx.
    #  6. Rule 2 matches the rule's type=direct with the requested 
    #     lookup of type=direct.
    #  7. Rule 2 is the matching rule and the decision is 'deny'.
    #

1.5.2.4. Specifying ACL Permissions

Now that we have seen the ACL syntax, we will provide representative examples and guidelines for ACL files.

Most ACL files begin by defining 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

Rules in an ACL file grant or deny specific permissions to users or groups:

    acl allow carlt@QPID create exchange name=carl.*
    acl allow rob@QPID create queue
    acl allow guest@QPID bind exchange name=amq.topic routingkey=stocks.rht.#
    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 allow all consume queue
    acl allow all bind exchange
    acl deny all all

In the previous example, the last line, acl deny all all, denies all authorizations that have not been specifically granted. This is the default, but it is useful to include it explicitly on the last line for the sake of clarity. If you want to grant all rights by default, you can specify acl allow all all in the last line.

ACL allows specification of conflicting rules. Be sure to specify the most specific rules first followed by more general rules. Here is an example:

    group users alice@QPID bob@QPID charlie@QPID
    acl deny  charlie@QPID create queue
    acl allow users        create queue
    acl deny all all

In this example users alice and bob would be able to create queues due to their membership in the users group. However, user charlie is denied from creating a queue despite his membership in the users group because a deny rule for him is stated before the allow rule for the users group.

Do not allow guest to access and log QMF management methods that could cause security breaches:

    group allUsers guest@QPID
    ...
    acl deny-log allUsers create link
    acl deny-log allUsers access method name=connect
    acl deny-log allUsers access method name=echo
    acl allow all all

1.5.3. User Connection and Queue Quotas

The ACL module enforces various quotas and thereby limits user activity.

1.5.3.1. Connection Limits

The ACL module creates broker command line switches that set limits on the number of concurrent connections allowed per user or per client host address. These settings are not specified in the ACL file.

    --max-connections          N
    --max-connections-per-user N
    --max-connections-per-ip   N
		    

If a switch is not specified or the value specified is zero then the corresponding connection limit is not enforced.

max-connections specifies an upper limit for all user connections.

max-connections-per-user specifies an upper limit for each user based on the authenticated user name. This limit is enforced regardless of the client IP address from which the connection originates.

max-connections-per-ip specifies an upper limit for connections for all users based on the originating client IP address. This limit is enforced regardless of the user credentials presented with the connection.

  • Note that addresses using different transports are counted separately even though the originating host is actually the same physical machine. In the setting illustrated above a host would allow N_IP connections from [::1] IPv6 transport localhost and another N_IP connections from [127.0.0.1] IPv4 transport localhost.
  • The max-connections-per-ip and max-connections-per-user counts are active simultaneously. From a given client system users may be denied access to the broker by either connection limit.

1.5.3.2. Queue Limits

The ACL module creates a broker command line switch that set limits on the number of queues each user is allowed to create. This settings is not specified in the ACL file.

    --max-queues-per-user N
		    

If this switch is not specified or the value specified is zero then the queue limit is not enforced.

The queue limit is set for all users on the broker based on the authenticated user name.

1.5.4. Encryption using SSL

Encryption and certificate management for qpidd is provided by Mozilla's Network Security Services Library (NSS).

Enabling SSL for the Qpid broker

  1. You will need a certificate that has been signed by a Certification Authority (CA). This certificate will also need to be trusted by your client. If you require client authentication in addition to server authentication, the client's certificate will also need to be signed by a CA and trusted by the broker.

    In the broker, SSL is provided through the ssl.so module. This module is installed and loaded by default in Qpid. To enable the module, you need to specify the location of the database containing the certificate and key to use. This is done using the ssl-cert-db option.

    The certificate database is created and managed by the Mozilla Network Security Services (NSS) certutil tool. Information on this utility can be found on the Mozilla website, including tutorials on setting up and testing SSL connections. The certificate database will generally be password protected. The safest way to specify the password is to place it in a protected file, use the password file when creating the database, and specify the password file with the ssl-cert-password-file option when starting the broker.

    The following script shows how to create a certificate database using certutil:

    mkdir ${CERT_DIR}
    certutil -N -d ${CERT_DIR} -f ${CERT_PW_FILE}
    certutil -S -d ${CERT_DIR} -n ${NICKNAME} -s "CN=${NICKNAME}" -t "CT,," -x -f ${CERT_PW_FILE} -z /usr/bin/certutil
    

    When starting the broker, set ssl-cert-password-file to the value of ${CERT_PW_FILE}, set ssl-cert-db to the value of ${CERT_DIR}, and set ssl-cert-name to the value of ${NICKNAME}.

  2. The following SSL options can be used when starting the broker:

    --ssl-use-export-policy

    Use NSS export policy

    --ssl-cert-password-file PATH

    Required. Plain-text file containing password to use for accessing certificate database.

    --ssl-cert-db PATH

    Required. Path to directory containing certificate database.

    --ssl-cert-name NAME

    Name of the certificate to use. Default is localhost.localdomain.

    --ssl-port NUMBER

    Port on which to listen for SSL connections. If no port is specified, port 5671 is used.

    --ssl-require-client-authentication

    Require SSL client authentication (i.e. verification of a client certificate) during the SSL handshake. This occurs before SASL authentication, and is independent of SASL.

    This option enables the EXTERNAL SASL mechanism for SSL connections. If the client chooses the EXTERNAL mechanism, the client's identity is taken from the validated SSL certificate, using the CNliteral>, and appending any DCliteral>s to create the domain. For instance, if the certificate contains the properties CN=bob, DC=acme, DC=com, the client's identity is bob@acme.com.

    If the client chooses a different SASL mechanism, the identity take from the client certificate will be replaced by that negotiated during the SASL handshake.

    --ssl-sasl-no-dict

    Do not accept SASL mechanisms that can be compromised by dictionary attacks. This prevents a weaker mechanism being selected instead of EXTERNAL, which is not vulnerable to dictionary attacks.

    Also relevant is the --require-encryption broker option. This will cause qpidd to only accept encrypted connections.

Enabling SSL in Clients

C++ clients:

  1. In C++ clients, SSL is implemented in the sslconnector.so module. This module is installed and loaded by default in Qpid.

    The following options can be specified for C++ clients using environment variables:

    Table 1.11. SSL Client Environment Variables for C++ clients

    SSL Client Options for C++ clients
    QPID_SSL_USE_EXPORT_POLICY Use NSS export policy
    QPID_SSL_CERT_PASSWORD_FILE PATH File containing password to use for accessing certificate database
    QPID_SSL_CERT_DB PATH Path to directory containing certificate database
    QPID_SSL_CERT_NAME NAME Name of the certificate to use. When SSL client authentication is enabled, a certificate name should normally be provided.

  2. When using SSL connections, clients must specify the location of the certificate database, a directory that contains the client's certificate and the public key of the Certificate Authority. This can be done by setting the environment variable QPID_SSL_CERT_DB to the full pathname of the directory. If a connection uses SSL client authentication, the client's password is also needed—the password should be placed in a protected file, and the QPID_SSL_CERT_PASSWORD_FILE variable should be set to the location of the file containing this password.

  3. To open an SSL enabled connection in the Qpid Messaging API, set the protocol connection option to ssl.

Java clients:

  1. For both server and client authentication, import the trusted CA to your trust store and keystore and generate keys for them. Create a certificate request using the generated keys and then create a certificate using the request. You can then import the signed certificate into your keystore. Pass the following arguments to the Java JVM when starting your client:

    -Djavax.net.ssl.keyStore=/home/bob/ssl_test/keystore.jks
    -Djavax.net.ssl.keyStorePassword=password
    -Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks
    -Djavax.net.ssl.trustStorePassword=password
    

  2. For server side authentication only, import the trusted CA to your trust store and pass the following arguments to the Java JVM when starting your client:

    -Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks
    -Djavax.net.ssl.trustStorePassword=password
    

  3. Java clients must use the SSL option in the connection URL to enable SSL encryption, e.g.

    amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672?ssl='true''
    
  4. If you need to debug problems in an SSL connection, enable Java's SSL debugging by passing the argument -Djavax.net.debug=ssl to the Java JVM when starting your client.