Securing WebWorks applications

The content of your WebWorks application runs inside a standard BlackBerry smartphone or BlackBerry PlayBook tablet application, so the application can use the same policy and security configuration that other applications use. You do not need to sign an application to run it in on a simulator, however, for BlackBerry tablet and BlackBerry 10 applications, you must install a debug token to run the unsigned application on a device. For BlackBerry smartphone applications running BlackBerry 7 or earlier, you must sign the .cod file to run your application on a device.

Inside a BlackBerry WebWorks application, you can specify that the application can access BlackBerry WebWorks APIs for a domain in an executable context. An executable context is a container in which you can run JavaScript code within the context of a web page. An executable container can be a page, a frame, or an iframe. If a local page provides the BlackBerry WebWorks API with access to the menu and linked in JavaScript code, you can include the domain by using application permissions for the executable container without specifying any feature elements.

Allowing access to external resources and APIs

By default, BlackBerry WebWorks applications cannot access data from external resources. For example, a BlackBerry WebWorks application cannot retrieve an HTML web page or make an AJAX request to a web service, unless you configure the application to allow access.

To allow access to external resources and BlackBerry WebWorks APIs, you must specify in the configuration document for the application the resources and the APIs that you require. You can define the list of domains that your application is allowed to access and the BlackBerry WebWorks APIs that are allowed for each domain. You can define this list using application permissions.

The BlackBerry WebWorks Packager follows the same origin policy for the resources that the application requests by matching the resources to entries in the permissions list.

Whenever you retrieve content from external resources, consider the following best practices to help make the application as secure as possible:
  • Provide JavaScript access to sensitive APIs only to trusted and secure web sites.
  • Use the same precautions that you would use for a hosted web site, to protect against users with malicious intent.
  • Protect your communication channel by using HTTPS when you expose sensitive APIs to the domain.

In the following example, we use the access element to specify that the site is accessed only over HTTPS to the specified APIs: 

<access uri="https://somedomain.com" subdomains="true">
  <feature id="blackberry.app" version="1.0.0.0" required="true"/>
  <feature id="blackberry.invoke" version="1.0.0.0" required="true"/>
</access>

Allowing requests to any web site

If your application is designed to access data from an unknown domain or a changing domain, you can use the access element with the wildcard character (*) to make sure that your requests are not blocked.

The wildcard character (*) cannot be used for data accessed by XMLHttpRequest, in this case, you must explicitly specify each domain.

When you use the wildcard character (*), web pages that your application accesses cannot access any of the application APIs.

In the following code sample, all requests that do not access content via XHR and that do not require access to application APIs are allowed:
<access uri ="*"/>

Allowing requests to specific web sites

If your application is designed to access API functionality on a domain, you must use the access and feature elements to specify the domain to make sure that your requests are not blocked.

You must explicitly specify each domain; you cannot use a wildcard (*) character to whitelist domains.

For example, if you want to update or change menu items from a domain, you must specify the domain and the APIs that you require.

In this example, the APIs that you specify under the domain mydomain are allowed. The ellipses in the example represent specific APIs that your application uses. 
<access uri ="mydomain" subdomains="true">
      <feature id=". . ." />
      <feature id=". . ." />
</access>