Manifest

Revision 2 as of 2013-06-28 22:10:37

Clear message

Manifest file - security

Overview

http://bazaar.launchpad.net/~click-hackers/click/trunk/view/head:/doc/file-format.rst discussed the manifest file format for click packages in general. This page discusses the security section of the JSON manifest. Click packages will contain the toplevel 'security' key, and the 'security' is itself a dictionary with each subkey representing a profile. The aa-easyprof tool is used to parse the security section of the manifest and generate an AppArmor profile. aa-easyprof will be used by click via a hook to install AppArmor policy. For more details on aa-easyprof, see man 8 aa-easyprof. An example manifest representing all possible keys is: 

{
  "name": "Name used by click",
  "version": "Version used by click>",
  "framework": "Framework used by click",
  "security": {
    "com.example.foo": {
      "abstractions": [
        "audio",
        "gnome"
      ],
      "author": "Your Name",
      "binary": "/opt/foo/**",
      "comment": "Unstructured single-line comment",
      "copyright": "Unstructured single-line copyright statement",
      "name": "My Foo App",
      "policy_groups": [
        "networking",
        "user-application"
      ],
      "policy_vendor": "somevendor",
      "policy_version": 1.0,
      "read_path": [
        "/tmp/foo_r",
        "/tmp/bar_r/"
      ],
      "template": "user-application",
      "template_variables": {
        "APPNAME": "foo",
        "VAR1": "bar",
        "VAR2": "baz"
      },
      "write_path": [
        "/tmp/foo_w",
        "/tmp/bar_w/"
      ]
    }
  }
}

Security keys

  • profile name: each profile is represented as a dictionary object. Therefore in the above example, "com.example.foo" is the profile name and the contents of the "com.example.foo" dictionary represent the profile.

  • binary: path to binary for this policy when using path-based attachment

  • author: author of the policy

  • comment: comment for the policy

  • copyright: copyright of the policy

  • name: name of policy. If not specified, use the name of the binary. This is not the AppArmor profile name.

  • policy_vendor: the vendor for policy groups and templates

  • policy_version: version of the vendor policy

  • template: template to use

  • template_variables: list of template variable assignments

  • abstractions: list of AppArmor abstractions to include (typically from /etc/apparmor.d)

  • policy_groups: list of AppArmor policy groups to include

  • read_path: list of paths to allow read access

  • write_path: list of paths to allow write access

aa-easyprof is a general purpose tool and all of the security keys are optional.

Use in Ubuntu

Click

Click packages in Ubuntu are required to run under application confinement and therefore the manifest file must contain a security section.

  • Required fields
    • JSON profile object (ie, the profile name key and its corresponding dictionary)
    • policy_vendor should be set to "ubuntu"
    • policy_version should be set. 1.0 is the first supported Ubuntu policy version. For other versions, see /usr/share/apparmor/easyprof/templates/ubuntu/ and /usr/share/apparmor/easyprof/policygroups/ubuntu/

    • binary - should be set as a recursive glob on the toplevel installation directory. Eg, if the app is installed to /opt/com.ubuntu.developer/com.ubuntu.developer.username.myapp, then binary should be set to /opt/com.ubuntu.developer/com.ubuntu.developer.username.myapp/**

    • template - defaults to 'default' which is a symlink to ubuntu-sdk. See aa-easyprof --policy-vendor=ubuntu --policy-version=1.0 --list-templates (using the appropriate vendor version) for a list of other templates

    • template_variables - the Ubuntu templates support setting the following variables:

      • APPNAME - typically the reverse domain (eg, com.ubuntu.developer.username.appname). This is used to differentiate application paths. Eg:

         @{APPNAME}=com.ubuntu.developer.username.myapp
 ...
   /opt/com.ubuntu.developer/@{APPNAME}/** r,

    • policy_groups - these are used to grant permissions to the app, such as netowrking, online accounts, content picking, etc. Some policy groups might always be used, such as qmlscene while others will only be used by some apps (eg, qmlscene-webview for HTML5 apps). See aa-easyprof --policy-vendor=ubuntu --policy-version=1.0 --list-policy-groups for a complete list

  • Red-flagged for manual review (use should actively be discouraged with updates made to policy groups and templates)
    • abstractions
    • read_path
    • write_path
  • Unused/ignored
    • name
    • author
    • comment
    • copyright

Traditional packaging

Traditional packaging can also leverage aa-easyprof, but the process is slightly more involved. In general, the following need to happen (see man dh_apparmor for details):

  • the manifest file (only the security section is needed) is added to debian/
  • aa-easyprof is given the manifest file to generate a profile
  • the profile is installed into a package

  • the postinst loads the AppArmor policy into the kernel

This is made easier with dh_apparmor. Create a manifest file following the above instructions then:

  1. put the manifest file in debian/manifest.json

  2. adjust debian/control to Build-Depends on dh-apparmor >= 2.8.0-0ubuntu14

  3. update debian/rules to call dh_apparmor. Eg:

    override_dh_install:
        dh_apparmor -p<deb binary> --profile-name=<profile name from the manifest> --manifest=manifest.json
        dh_install

    and then to clean up:

    override_dh_clean:
        dh_clean
        rm -rf debian/apparmor

  4. install the files. Eg, add to debian/<deb binary>.install:

    debian/apparmor/<profile name> etc/apparmor.d

The remaining consideration is making sure that the app runs confined. If the application provides an executables (eg, ELF binary, executable python script), then specifying the 'binary' in the manifest is enough. If instead a helper is being used, such as qmlscene, then it is easier to update the .desktop file. Eg, instead of this:

Exec=qmlscene <path to>.qml

Use this:

Exec=aa-exec -p <profile name> qmlscene <path to>.qml

This last step should not be required if the application uses the new Ubuntu application lifecycle and is started via Upstart jobs.