Authorization Manager (authman)

Indicate whether a process has access to requested system services or resources

Synopsis:

authman [-b] [-c] [-U uid[:gid]] [-v]

Runs on:

QNX Neutrino

Options:

-b
Disable background launch (i.e., launch in the foreground).
-c
Specify the configuration file to use for running authman. The default is /etc/authman/authman.cfg.
-U uid[:gid]
Run with the specified credentials when possible, to avoid running as root all the time. When started, authman runs as root to perform privileged operations. If you use the -U option, the service drops its credentials to the user ID (uid) and the group ID (gid), if it's provided. The argument format must match the format in the /etc/passwd and /etc/group files.
-v
Increase output verbosity. The -v option is cumulative; each additional v increases the level of verbosity, up to three levels (-vvv).

Description:

The Authorization Manager (authman) is a resource manager that handles requests from other processes to access system services they may need, such as the PPS filesystem, system paths, permissions, or OS system calls. The authman service uses a set of capabilities to protect system services from unauthorized use. Capabilities specify the apps that can use a particular service.

Although authman is responsible for determining whether an app can use the services it wants to use, the app doesn't send requests directly to authman. Instead, the Application Launcher (launcher) does this on the app's behalf. When asked to launch an app, the launcher process asks authman to confirm that the app has permission to use the requested capabilities.

Launcher is responsible for handling situations when the app isn't allowed access to the requested resources. If Launcher allows the app to run without certain capabilities, the app is responsible for handling how to run without having access to all the resources that it requires.

The authorization process is as follows:

  1. When an app is packaged, its MANIFEST.MF file contains any capabilities that were listed in the <action> element in the bar-descriptor.xml file.
  2. When it receives a request to launch an app (e.g., from the HMI), the launcher process reads the app's MANIFEST.MF file for the requested capabilities (e.g., Entry-Point-System-Actions: access_shared).
  3. The launcher process asks authman to confirm that the app is entitled to do what it wants to do.
  4. The authman process checks the sys.res file to see if the app has an allow permission for each requested capability.
  5. If authman returns true for the capability request, launcher starts the app and the app can access all the resources it needs. If authman returns false, launcher can still start the app, but the app must run with fewer resources.

Files used for authorization

The following files are used when the system attempts to launch an app:

File Description
/apps/name/native/bar-descriptor.xml A configuration file that accompanies the app's BlackBerry ARchive (BAR) file, which contains all the app's code and resources. The bar-descriptor.xml file lists an app's assets, window attributes, capabilities (given in the <action> element), and more. This file is primarily used by the tools, which use its information to generate the manifest file, MANIFEST.MF.
/apps/name/META-INF/MANIFEST.MF Generated during packaging, the MANIFEST.MF file contains various identifiers for the app, as well as the capabilities it wants to access (e.g., access_internet).
/etc/authman/sys.acl Lists all the capabilities and their associated ACL (access control list) filesystem permissions. The authman process reads this file to determine whether an app has the permissions it needs.
/etc/authman/sys.res Lists the available system capabilities and the apps that are entitled to use them. The authman process checks this file before authorizing an app to be launched.

Format for the sys.acl file

This file lists all the available capabilities, along with the filesystem permissions for particular paths that apps may use. These paths are typically PPS directories, but you can specify any paths.

Note: To ensure your authorization rule changes are permanent, modify the sys.acl file on your host or development system. This file is found in $QNX_DEPLOYMENT_WORKSPACE/target/etc/authman/. Any changes made to the sys.acl copy on the target are lost when you rebuild and redeploy the image. You should refer to the Getting Started guide for the value of the QNX_DEPLOYMENT_WORKSPACE variable.
Note: If a capability isn't listed in this file but an app requests that capability, the app is given access to it, based on the default authman behavior. Keep this default behaviour in mind to properly secure your system.

To define a capability, you must list its name on a separate line and list any actions that apply to it on subsequent lines, which must be indented. The general format is as follows:

capability_name
     ACTION flags [arguments]*
     ...

The capability_name field is a string that stores the capability name. The authman service supports these actions:

ACL (Access Control List)
Assigns permissions to paths accessible with that capability
MAC (Macro)
Invokes a macro, which is a group of actions
PAB (Procmgr Ability)
Defines procmgr abilities, which control the operations that applications are permitted to do (if they're granted the enclosing capability)

An action can be followed by certain flags, depending on the action. The authman service supports these flags:

opt
Indicates the action is optional, meaning if it fails, the other actions for the capability can still be applied. Without this flag, failure of the action causes authman to roll back the entire capability.
override_gid
Apply the action to this group ID (GID) instead of the app's GID. Overriding the GID on an action is useful when a service needs to create internal processes with unique GIDs.

Access control lists

Each access control list (ACL) action applies a permissions mask to a particular path:

capability_name
     ACL [opt] group_mode[:other_mode] [path]

where:

opt
Specifies that this ACL is optional to the capability. If this option isn't used and the path subsequently specified isn't available, the permission is rolled back. The opt string is useful when a path might not be present. For example, when a PPS object gets created later.
group_mode[:other_mode]
Specifies group and optionally, other permissions for the path that follows. Each mode can contain any combination of the read (r), write (w), and execute (x) permissions.
By default, authman clears all the other bits to control path access strictly by group, but you can retain those bits by defining them in this flag. This option is useful for retaining execute permissions on a directory when a write ACL is applied. It's also useful for making a file readable for everyone, but writeable only by the ACL.
path
Provides the filepath or directory to access. It's common to point to a PPS object path, but it can be any filepath or location.

For example:

read_geolocation
    ACL opt rw /pps/services/geolocation/control
    ACL rw /pps/services/geolocation/status

The entry above indicates that any app that wants to use the read_geolocation capability has read and write permissions on the /pps/services/geolocation/control and /pps/services/geolocation/status objects. If /pps/services/geolocation/control doesn't exist, access to /pps/services/geolocation/status still applies, provided it's available.

Macros

You can define macros to group actions together and to reuse them in multiple capabilities and for many GIDs. A macro must be defined before its first usage in a capability (i.e., earlier in the configuration file), as follows:

macro macro_access_deviceproperties_private
    ACL x /pps/services/private
    ACL r /pps/services/private/deviceproperties

The entry above defines the macro_access_deviceproperties_private macro, which groups two ACL actions. These actions allow apps to navigate to the /pps/services/private directory (by assigning it the x permission) and to read the /pps/services/private/deviceproperties file (by assigning it the r permission).

You can use the MAC action to invoke actions from another capability as follows:

read_device_identifying_information
    MAC macro_access_deviceproperties_private
    MAC macro_access_device_properties

The read_device_identifying_information capability performs the actions in the macro_access_deviceproperties_private and macro_access_device_properties macros. Although not shown here, the opt flag can be specified for a MAC action; this way, if any action in the referenced macro fails, the other capability actions can still be applied. You can also use the override_gid flag to apply a GID to the multiple paths defined by the ACLs within a macro.

Note: When using macros, you must be careful not to create duelling capabilities, which occur when two capabilities apply an ACL to the same path. This causes problems because if one ACL grants access to a path while the other ACL denies access, the capability that was processed last is the winner.

Procmgr abilities

Procmgr abilities are process-manager settings that control which operations are permitted for a particular process. When given these abilities, a process obtains functionality normally restricted to root.

Using PAB actions, you can define procmgr abilities for a capability as follows:

capability_name
     PAB ability_name inheritance_flag
      [sr1_low-sr1_high [... sr5_low-sr5_high]]

The ability_name string following the PAB keyword indicates the ability being granted. The abilities supported by the Apps and Media SDK are listed in the procmgr_ability() description found in the QNX Neutrino C Library Reference. Note that this list provides the numeric constants that can be passed to the library function; in the sys.acl file, however, you must refer to abilities by using strings. The string name for an ability is the name of its numeric constant without the PROCMGR_AID_ prefix. Also, authman reads the ability strings in a case-insensitive manner. This means you can use child_newapp in sys.acl to refer to the ability represented by PROCMGR_AID_CHILD_NEWAPP.

The inheritance_flag must be either inherit_yes (to ensure this new ability setting is inherited by child processes) or inherit_no (to ensure the setting isn't inherited, which is the default behavior).

Depending on the ability, you can define one or more value subranges (in the srN_low and srN_high fields). The units and meaning of these values are specific to the ability. For example, the PROCMGR_AID_SPAWN_SETGID and PROCMGR_AID_SPAWN_SETUID abilities accept lower and upper bounds on the GIDs or UIDs that a process can assign to a child process. The PROCMGR_AID_MEM_LOCK ability locks a range of the process address space into physical memory; in this case, the range arguments specify the start and end addresses.

The following capability rule defines multiple abilities that have different inheritance and subrange values:

is_launch_delegate
    PAB setuid inherit_yes 1-2147483647
    PAB setgid inherit_yes 1-2147483647
    PAB child_newapp inherit_no
    PAB pathspace inherit_no

The PAB statements shown above assign abilities to applications granted the is_launch_delegate capability. These applications can then assign any UID or GID to their child processes, as indicated by the maximum numeric range given for the setuid and setgid abilities. They can also create a new application ID for a child process (as indicated by child_newapp), and add items to the kernel pathname prefix space (as indicated by pathspace).

Format for the sys.res file

This file is used to restrict authorization—only the particular apps listed under each available capability can use that capability.

Note: To ensure your authorization rule changes are permanent, modify the sys.res file on your host or development system, for the reason explained in the sys.acl file description.
Note: If a capability is defined in the sys.acl file but not listed in sys.res, an app requesting that capability is automatically granted access to it (effectively allow *). It's important to remember this default behavior to properly secure your system.

The format to define access to a capability is as follows:

capability_name
    [allow|deny] [application-name|application-name*|*]
capability

Here's an example of how to allow any apps to use the access_internet capability:

access_internet
    allow *

In the example above, any is indicated by the wildcard (*).

Conversely, if you want specific apps to access a capability, you can define a whitelist. A whitelist gives access or privileges to those that are listed, but denies access to all other apps or processes. You can specify apps and processes using a partial name and wildcard (*) or using a full name. The names of apps can be determined when you install them on the target. For example, the following specification grants the access_special_info capability to apps with names beginning with mybrowser (e.g., mybrowser_one) and to an app with the full name mydemo.testDev_emodemod448125f :

access_special_info
    deny *
    allow mybrowser*
    allow mydemo.testDev_emodemod448125f 

Predefined capabilities

After a capability is granted, it allows an app to use a service that would be otherwise restricted. This consideration is important when you are designing capabilities for your system. You can define any number of capabilities. In addition, your host and target image may come with predefined capabilities that you can use and build into your image. Here are the capabilities provided for the QNX SDK for Apps and Media:

Capability Description
access_demo Do not use in production systems. This capability is used for the Cordova PPS Demo sample, which shows how to restrict application access to a PPS object and how to define a whitelist. For information about this permission, see "Adding a permission to access a PPS object" in the HTML5 Developer's Guide.
access_internet Use the internet connection from a Wi-Fi, wired, or other type of connection to access locations that are not local on the target.
access_shared Read and write files shared between applications that run on the target.
audio_manager_access Access restricted Audio Manager capabilities that include, but aren't limited to, adjusting volume and voice configuration features. For more information, see the functions in the Audio Manager API.
configure_system Configure system-level functionality, such as network settings, restarting, or shutting down of the target.
read_geolocation or access_location_services Read the target's current location. This location is determined based on the assigned IP address.

The capabilities listed below may be found in the sys.acl and sys.res files installed on your host. These capabilities are required for authman to function correctly but are for internal use only. Don't remove any of the permissions below, as it may cause undefined behavior:

Configuration file

The authman configuration file provides additional controls for enabling access to system services, based on process permissions and capability names. For instance, you can define client whitelists to restrict the commands that client applications can issue to authman. These commands provide dynamic updates to your security configuration, such as setting and deleting capabilities for applications.

Each whitelist names the commands that clients with a certain set of credentials (i.e., process permissions) can use. Entries in this configuration section have the following form:

username= <username>, ["default"|override_uid], ["default"|override_gid],
 <cmd_1>, <cmd_2>, ..., <cmd_N>

When "default" is given for the UID or GID, the permission setting in /etc/passwd is used. You can override the permissions by defining the override_uid and/or override_gid values. Consider this excerpt:

[client_whitelist]
#         USERNAME        UID      GID      CMDS LIST
username= apps,           default, 0,       chkcap

This command ensures that clients with the username apps, running with their default UID and a GID of 0, can issue the chkcap command to the authman service.

You can also whitelist the paths that can be affected by rule files loaded at runtime. The owner of a capability prefix, which is used to represent a capability category, can send the load command to authman to dynamically load, from an .acl or a .res file, a set of capability-based pathname permissions or application access settings. In the configuration file, each whitelist statement contains a capability prefix followed by a path. The statement ensures that only those apps with a dynamically loaded capability that begins with the stated prefix can access the path that follows. Apps without capabilities based on this prefix can't access the path.

The default configuration file defines these prefix-based paths:

[capability_prefix_paths]
prefix=cds, /pps/services/networking/control
prefix=cds, /pps/services/networking/status
prefix=cds, /pps/services/networking/proxy
prefix=cds, /pps/services/wifi/status

These settings ensure that only apps that are granted capabilities with the cds prefix at runtime can access the stated PPS paths. The advantage of defining such whitelists is that they let you constrain the paths affected by certain capabilities without requiring someone with system expertise to review the rule files to ensure that they meet security requirements. Likewise, these files only define access settings and pathname permissions, for security reasons.