Example: Adding a permission to access a PPS object

You can use Authorization Manager (authman) to restrict access to Persistent Publish/Subscribe (PPS) objects.

Permissions and capabilities

As well as letting you persist information across device restarts, PPS is useful for sharing information between apps in a secure manner. You can use the Authorization Manager (authman) to restrict access to a PPS object and to limit the data one more multiple apps can access.

To create a permission, you edit the pps.conf file to create a capability. You can then configure access and restrictions to the resources and services for that new capability in the /etc/authman/sys.acl and /etc/authman/sys.res files.

After you have created a capability, use the <rim:permit> to specify the name of the capability in the config.xml in your HTML5 project. The <rim:permit> element in the config.xml file grants the HTML5 app access to the resources and services defined by the capability.

Note:

Before you begin, you should have a good understanding of authman, of PPS, and how to use PPS with an HTML5 app.

Setting a PPS object capability

The instructions below show you how to:

To perform these tasks:

  1. Modify the config.xml in your HTML5 project to grant access to a new permission called access_demo. To do this, add the <rim:permit> element beneath a <rim:permissions> element. The capability access_demo is defined in the next step. Here's how your config.xml might look after you have made this addition (shown in bold):
    <?xml version='1.0' encoding='utf-8'?>
    <widget id="CordovaPPSdemo" version="1.0.0.0"
            xmlns="http://www.w3.org/ns/widgets" 
            xmlns:rim="http://www.blackberry.com/ns/widgets">
        <name>Cordova PPS Demo</name>
        <author>QNX</author>
        <description>Cordova PPS  Demo</description>
        <content src="index.html" />
        <rim:permissions>
            <rim:permit>access_shared</rim:permit>
            <rim:permit>access_internet</rim:permit>
            <rim:permit>run_native</rim:permit>
            <rim:permit>access_demo</rim:permit>
        </rim:permissions>
        <feature name="com.qnx.demo" />
        <feature name="com.qnx.demo" value="com.qnx.demo" />
    </widget>
  2. On the target system, define the PPS object to the /etc/pps.conf file. This file lists the PPS objects to create. For example, to create a PPS object called qnx/demo and provide read-write access for everybody to the object, you add the following entries to the pps.conf file:
    qnx/demo
        0:0:0660:O_CREAT
        user::rw
        group::rw
        other::rw
        mask::rw
  3. On your target, create the capability. For example, to create the access_demo capability, add the name of the capability, and then list the PPS objects that are accessible in the /etc/authman/sys.acl file.
    access_demo
        ACL opt rwx:rw /pps/qnx/
        ACL opt rwx:rw /pps/qnx/demo
  4. On your target, configure the restrictions for the new capability in the /etc/authman/sys.res file. In this scenario, one app called CordovaPPSdemo is configured to access the PPS object. To restrict other apps from accessing the PPS object, but allow the CordovaPPSdemo app to access the PPS object, add the name of the capability, deny *, and allow [name of app] entries to the /etc/authman/sys.res file. For example:
    access_demo
        deny *
        allow CordovaPPSdemo.testDev_dovaPPSdemod339185a
    Note:

    The string "CordovaPPSdemo.testDev_dovaPPSdemod339185a" is determined when you build your app using the build debug command. The name is a combination of the package name and the package identifier. There are two ways to determine the string to use.

    • You can see the string that appears in the message after you use the bar-install command to install your .bar file.
    • You can unarchive the .bar file, then determine the string that's used from the META-INF/MANIFEST.MF file based on this algorithm:

      Package-Name+ '.' + Package-Id

      For example, based on the following MANIFEST.MF file, the name would be CordovaPPSDemo.testDev_dovaPPSdemod339185a:
      Archive-Manifest-Version: 1.5
      Archive-Created-By: BlackBerry WebKit BAR Packager 1.10
      
      Package-Type: application
      Package-Author: QNX
      Package-Author-Id: testUU5YICAgICAgICAgICAgICA
      Package-Name: CordovaPPSdemo
      Package-Id: testDev_dovaPPSdemod339185a
      Package-Version: 1.0.0.0
      Package-Version-Id: testMS4wLjAuMCAgICAgICAgICA
      ...
      ...

After the CordovaPPSdemo app is deployed, no other app may access the PPS object named qnx/demo. If you want another app to access this PPS object, add the generated name of the app to /etc/authman.sys using another allow entry as described above.