Security

SmartSockets offers username- and password-based security. This allows the RTserver to authenticate and authorize an RT process by:

verifying that the connecting RT process is who it claims to be

determining whether the connecting RT process is authorized to perform an action or access a resource

This is offered with Basic Security.

To enable Basic Security, edit the command file rtserver.cm, adding this line to set the SmartSockets option Sm_Security_Driver to basic:

setopt sm_security_driver basic

This command instructs the server to load the security command file sdbasic.cm. The file sdbasic.cm sets options for the Basic Security driver, such as the tracing level for logging security activity.

When Basic Security loads, it also reads and loads the access control list (ACL) configuration files. The ACL files are cached for the amount of time set in the Sd_Basic_Acl_Timeout option, then read again. If you make any changes to the ACL files after loading Basic Security, they do not take effect until the time specified in the Sd_Basic_Acl_Timeout option has passed, at which time the ACL files are reloaded.

Basic Security

SmartSockets Basic Security allows the RTserver to authenticate a user by requiring a username and password before accepting a connection. RTserver can also restrict access to resources by authorizing only certain users to access them. Basic Security uses a permission scheme to manage authorization. By setting permissions, you can control:

server connections — which RT processes, or users, can connect to RTserver

subject subscriptions — which users can subscribe to a subject

subject publications — which users can publish to a subject

Basic Security can also provide auditing information, written to file or standard output (stdout). This information gives details on which users passed or failed authentication and which users were granted or denied access to resources. See Sd_Basic_Trace_Level for more information.

Basic Security is managed through access control lists (ACLs). The ACL configuration files contain the usernames and passwords, group definitions, and permissions. The ACL files are stored in a file local to the machine which RTserver runs on, in the directory $RTHOME/acl. There are three configuration files:

users.cfg — lists the username and password for each user authorized to connect to RTserver

groups.cfg — defines groups, or categories, of users

acl.cfg — sets the user and group permissions

To change the configuration files, you must edit them directly.


	The ACL files are cached for the amount of time set in the Sd_Basic_Acl_Timeout option, then read again. If you make any changes to the ACL files after loading Basic Security, they do not take effect until the time specified in the Sd_Basic_Acl_Timeout option has passed, at which time the ACL files are reloaded.

Editing the Users File

The users.cfg file lists the username and password of each user authorized to connect to RTserver. The users list has this syntax:

users password_type { 
  username password 
}

where:


`password_type`	represents how the password is stored. The only available storage is `plain`, meaning the password is stored in plain text.
`username`	identifies an individual user. Each username is restricted to 64 characters.
`password`	is the password used to authenticate `username`. The password size is unlimited. To specify no password, use empty quotation marks (`""`).

There are two default users in the users.cfg file, admin and anonymous. admin uses the password smartsockets, while anonymous does not require a password. For example:

users plain { 
  admin smartsockets 
  anonymous "" 
}

To add new users, add the username and password to the list:

users plain { 
  jdoe txY3s3 
  mfrank foobar 
  admin smartsockets 
  anonymous "" 
}

Editing the Groups File

The groups.cfg file defines groups of users that can share permission values. Group definitions simplify maintenance of permissions. For example, you might create a group for all developers, dev, knowing that all developers require the same set of permissions.

The groups list has this syntax:

group name { 
  username 
}

where:


`name`	is the name of the group.
`username`	identifies a user as a member of the group. The `username` must be listed in the `users.cfg` file before it can be added to a group.

There is one predefined group, the admin group:

group admin { 
  admin 
}

The only member of the admin group is the user admin.

You can have more than one group. For example:

group dev { 
  jdoe 
  mfrank 
  anonymous 
} 
 
group admin { 
  jdoe 
}

In this example, there is only one member of the admin group, jdoe. The dev group includes two users plus the anonymous user.

The Admin Group

The admin group is reserved for users with administrative privileges, and prevents unauthorized users from publishing messages with the message type CONTROL. Only users who are included in the admin group can publish CONTROL messages. CONTROL messages are commonly used to send commands to other processes.

By default, the only user in the admin group is admin. Add or remove users from the group by editing the groups.cfg file. You can further define the admin group permissions in the acl.cfg file. You can restrict access to other message types with the option Sd_Basic_Admin_Msg_Types. See Sd_Basic_Admin_Msg_Types for more information.

Editing the Permissions File

The acl.cfg file sets the permissions for each user or group.


	Permissions are read from the bottom up. The first permission that applies to a user when the file is read is enforced.

All permissions use this syntax:

permission allow|deny user|group name host resource

where:


`permission`	is the type of permission set. Valid settings are: `server` — establishes which RTservers are permitted to connect. `client` — defines which RTclients are permitted to connect connection. `membership` — establishes which user-groups, primarily multicast groups, an RTclient can join. `subscribe` — defines which subjects an RTclient can subscribe to. `publish` — defines which subjects an RTclient can publish to.
`allow\|deny`	indicates whether the permission setting grants or denies authorization.
`user\|group`	designates whether the permission applies to a user or a group.
`name`	is the user or group whose permission is being defined. An asterisk applies to all users or groups.
`host`	is the TCP/IP address of the host being granted access. `host` must be a numeric address in a series of numbers separated by periods (`.`). For example, `10.105.42.4`. To indicate all hosts, use an asterisk (`*`). Use a partial address, such as `10.105`. to indicate all hosts whose address begins with `10.105`.
`resource`	is specific to the permission being set: when `permission` is `server`, no resource is defined; you must use an asterisk. when `permission` is `client`, use the name of the SmartSockets project. An asterisk indicates all projects. when `permission` is `membership`, use the user-group name. An asterisk indicates all user-groups. when `permission` is `subscribe`, use the subject being subscribed to. To indicate all subjects, use `...` or `/...` when `permission` is `publish`, use the subject being published to. To indicate all subjects, use `...` or `/...`

The order of permissions is very important. Permissions are read from the bottom up. The first permission that applies to a user when the file is read is enforced. This is an example of a client connection permission:

client allow user *    * rtworks 
client deny  user jdoe * rtworks

The top line allows all users to connect to the rtworks project. The bottom line prevents user jdoe from accessing that project. Notice that user jdoe matches both permissions. However, because the permissions are read from the bottom up, the last permission is enforced. jdoe is not permitted to connect to the rtworks project.


	You must authorize the RTclients’ unique subject, because the unique subject is not automatically authorized. If an RTclient is not authorized to receive messages sent to its unique subject, it will not receive administrative messages sent by RTserver. To allow all subscriptions to all RTclients’ default unique subjects you can use the permission: `subscribe allow user * * /__`

Using Wildcards

Wildcards (* or ...) can be used in permissions files to indicate multiple users or groups, connections, hosts, and subjects. A wildcard component using an asterisk (*) never matches more than one component. Use ellipsis (... or /...) to indicate multiple levels of components.

For example, if subscribe permissions are granted on subject /dev/*, the client has permission to subscribe to /dev/misc but does not have permission to subscribe to /dev or /dev/misc/src. To specify all subjects use /.... If the subject is not absolute, the RTserver’s default subject prefix is used to prefix the subject.

Example 24 Example Permission File

This is an example acl.cfg file:

/* Server Permissions                                                           */ 
/*                                                                                      */ 
/* 1: allow all RTservers from all hosts to connect                   */ 
server allow user * * * 
 
/* Client Permissions                                                           */ 
/*                                                                                      */ 
/* 1: allow all users in group admin when connecting from     */ 
/*    TCP/IP addresses beginning with 10.105. to any project  */ 
/* 2: allow all users in group dev from all hosts to any project  */ 
client allow group admin 10.105. * 
client allow group dev   *       * 
 
/* Subscription Permissions                                                 */ 
/*                                                                                      */ 
/* 1: allow all users from all hosts to subscribe to all subjects    */ 
/* 2: deny all users from subscribing to /admin/...                   */ 
/* 3: allow users in group admin to subscribe to /admin/...       */ 
subscribe allow user  *     * /... 
subscribe deny  user  *     * /admin/... 
subscribe allow group admin * /admin/... 
 
/* Publish Permissions                                                         */ 
/*                                                                                      */ 
/* 1: allow users in group dev to publish to /dev/...                 */ 
/* 2: deny user jdoe from from publishing to /dev/...                */ 
publish allow group admin * /admin/... 
publish deny  user  jdoe  * /admin/...

Setting the Username and Password

Connecting RT processes must know the username and password assigned to them in the RTserver’s users.cfg file. The username and password are set differently in daemon processes than they are in RTclients.

With RTclients, the username and password are set with the TipcSrvSetUsernamePassword function. With daemon processes such as RTserver and RTmon, you set the username and password by using two new command line arguments, -username and –password.

This example starts the RTserver and assigns the username server and password foobar:

rtserver –username server –password foobar


	On platforms that support both 32- and 64-bit, use the rtserver64 command to run the 64-bit version of RTserver.

An alternative to the command line argument and the TipcSrvSetUsernamePassword function is to use file-based credentials and the Auth_Data_File option. Set this option to a file containing the credentials you wish to send. File-based credentials are created with the RTacl tool.

For more information on the TipcSrvSetUsernamePassword function, see the TIBCO SmartSockets Application Programming Interface.

The RTacl Process

RTacl is a utility function provided as a debugging aid for users with complex access control list (ACL) permission files. RTacl is used to:

evaluate ACL configuration files

evaluate user permissions

create credential files, when used with the Auth_Data_File option

RTacl has an interactive interface. To start RTacl, type at the command line:

$ rtacl

RTacl displays the ACL> prompt, at which you can execute RTacl commands. To exit from RTacl and return to the operating system prompt, enter quit at the RTacl command prompt. For a full list of commands supported by RTacl, see RTacl Commands.

RTacl must load the ACL files before running any commands that require an ACL, such as evaluate, groups, or permissions. Use the load command to specify the ACL configuration and verify its syntax. For example:

ACL> load $RTHOME/acl

Once the ACL is loaded, use RTacl to evaluate the ACL files. For example, you can use RTacl to discover:

Whether a user has permission to subscribe to a particular subject (evaluate command).

Which users are included in the ACL (users command).

What groups are set and which users belong to each group (groups command).