FirefoxOS/New security model/Getting Started with Signed Packages

Getting Started with Signed Packages

Signed Packages are web packages that been signed with a signing key. In production, these are signed by MarketPlace, but for testing purposes, developers can configure their device to accept a test signing key, so they can sign their own packages for one specific device.

The steps in the process are:

• Create a regular gaia app
• Add additional required attributes to the manifest file
• Use the developer signing tool to create and sign your package
• Host the package in where you specify in the manifest file

Since the signed package support (i.e. new security model) is pref'ed out at the moment, you have to

• Configure a number of developer preferences
• Upload your signing certificate to your test device

before testing this feature.

The configuring steps will be covered in detail below.

Creating/Modifying a Signed Package

Signed Packages are similar to existing web apps packaged apps - i.e. they consist of HTML, JavaScript, CSS files and other resources, and are packed into a package with a manifest.webapp file. However, you don't need to create the package on your own. What you need to do is:

1. Write a Regular Gaia App

The first step to create and host your signed package is to create a normal gaia app. Claim the permissions/system message/web activity as usual in the manifest even though system message and web activity is still not supported at the moment.

2. Add Additional Required Attributes to the Manifest File

Beside the well-known attributes in the gaia manifest, there are two additional attributes required by signed package and you have to manually add to the manifest:

1. package-identifer: A UUID string to uniquely identify this package. The identifier will be considered as a part of the origin. So please be careful to change this value across versions.
2. moz-package-origin: The origin where the package is going to be hosted. This prevents the package from being downloaded and hosted by other people.

Note that the packaging/signing tool would automatically add additional attributes to the manifest like "moz-resources".

For example, your manifest file may look like the following:

{
  // Regular manifest attributes.
  ...,
  ...,
  ...,
  
  // New attributes introduced by NSec.
  "package-identifier": "3bd9a32f-8fd6-404f-bfbe-b883d2e93646",
  "moz-package-origin": "http://people.mozilla.org" 
}

After packaging and signing, it becomes:

{
  // Regular manifest attributes.
  ...,
  ...,
  ...,
  
  // New attributes introduced by NSec.
  "package-identifier": "3bd9a32f-8fd6-404f-bfbe-b883d2e93646",
  "moz-package-origin": "http://people.mozilla.org",
  //
  // Auto-generated part.
  "moz-resources": [...],
}

3. Create and Sign Your Package

• Install a signing tool
• Follow the tool instructions to sign the package

4. Host Your Package

• Signed Packages are hosted as a file on a web server. The only requirements are:
  • The package is served with the MIME type of “application/package”
  • The package is served from the location specified in the manifest (moz-package-origin)

Now you can use [URL-of-the-package]!//[resource-path-relative-to-the-package] to access the packaged web content via browser. For example, if you host your package in http://foo.com/app.pak, the path to "index.html" inside the package would be http://foo.com/app.pak!//index.html.

Preparing a Device to Load Signed Packages

In order to test Signed Packages on a device, you must upload your developer certificate to the device, and configure a number of preferences to both enable Signed Packages, and also to switch to trusting the developer certificate.

Configure your device

If you have not already done so, you will need to enable remote debugging via DevTools, and grant additional access. (Enable remote debugging in the developer menu of the device. Use WebIDE to request higher privileges, and then access the preferences section. For information on how to do this, see here.)

• Upload the develop certificate created during signing to an accessible location:

 adb push developercert.der /data/local/developercert.der 

• Configure a number of preferences as follows:
  • Enables web packages support: network.http.enable-packaged-apps = true
  • Enables Signed Package support: network.http.signed-packages.enabled = true
  • Create a network.http.signed-packages.developer-root preference using the path you created in the previous step: network.http.signed-packages.developer-root = /data/local/developercert.der
• Restart b2g or restart the device.

Limitations

System Messages is not supported yet. Any function related to System Message cannot be used for now.