Indicate whether a process has access to requested system services or resources
authman [-b] [-c] [-U uid[:gid]] [-v]
QNX Neutrino
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:
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.
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:
An action can be followed by certain flags, depending on the action. The authman service supports these flags:
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:
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.
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.
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.