Authorization Manager (authman)

Overview

The Authorization Manager (authman) is a resource manager that handles requests from other processes to access services they may need, such as access to the PPS filesystem or to OS system calls. Enforcing the specified security model, authman ensures that apps can use only the services they're authorized to use.

Although authman is responsible for allowing an app to 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.

The authorization process is as follows:

When an app is packaged, its MANIFEST.MF file will contain any capabilities that were specified in the <action> element in the bar-descriptor.xml configuration file.
When a request to launch an app occurs (e.g. from the HMI), the launcher process reads the app's MANIFEST.MF file for requested capabilities (e.g. Entry-Point-System-Actions: run_native).
The launcher process then asks authman to confirm that the app is entitled to do what it wants to do.
The authman process checks the sys.res file to see if the app has an allow permission for the action in question.
If authman returns true for the capability request, then launcher can launch the app.

Synopsis

authman [-a uid | -b | -p prio | -v]

Options

-a uid: Load restrictions for this account user ID.
-b: Disable background launch (i.e., launch in the foreground).
-p prio: Run authorization at this priority level.
-v: Increase output verbosity. The -v option is cumulative; each additional v adds a level of verbosity.

Files used for authorization

The following files participate 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), etc.
/apps/`<name>`/META-INF/MANIFEST.MF	Generated during packaging, the MANIFEST.MF file contains various identifiers for the app as well as desired capabilities (e.g. `run_native`).
/etc/authman/sys.acl	Lists all the capabilities and their associated ACL (access control list) filesystem permissions. The launcher 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.

sys.res file format

This file is used to restrict authorization—only the particular apps listed under each available capability can use that capability. The file also specifies how apps may use the capability. The format is as follows:

<capability>
    <allow|prompt|deny> <application-name|application-name*|*> 
</capability>

Here's an example:

play_audio
    allow *

This means that any (indicated by the wildcard *) app is allowed to play audio.

sys.acl file format

This file lists all the available capabilities, along with the filesystem permissions for particular PPS objects that an app may use. The format is as follows:

<capability>
     ACL r|rw|rwx <pps_path>

For example:

read_geolocation
    ACL rw /pps/services/geolocation/control

This entry indicates that any app wishing to use the read_geolocation capability will have read and write permissions on the /pps/services/geolocation/control object.

Capabilities

The authman service relies on a set of capabilities to protect system services from unauthorized use. Once granted, a capability allows an app to use a service that would otherwise be restricted.

Here are the most commonly used capabilities:

Capability	Description
`access_shared`	Read and write files that all applications can share.
`play_audio`	Play an audio stream.
`read_geolocation`	Read the device's current location.
`record_audio`	Access the audio stream from the device's microphone.
`set_audio_volume`	Change the volume of a playing audio stream.