Security model for access to DOM properties and functions
2010-01-05 / msimonides@opera.com

Overview of the Problem
=======================

Access to properites (and function invocation) on builtin DOM objects must be
protected depending on user choice and settings, environment (widget type etc.)
and possibly other factors.

The reason is that new APIs are being introduced that give access to privileged
information (e.g. user's position or address book entries) or actions (file
manipulation, application launching etc.).

The direct reason for implementing this security model was the implementation of
JIL Handset API support but it may also be used for APIs like geolocation and
with some extensions also Bondi and others.
That's why the current requirements presented below reflect mostly what is
required by the JIL Handset API.

The security decisions need to be made based on several factors:
- user's answer to a direct question asking whether to allow a specific action,
- previously saved user's answer (e.g. saved for a session or persistently for
  "ever"),
- widget type (XML namespace on the <widget> tag in config.xml),
- whether the widget is signed or not,
- whether the widget is signed by a specific privileged certificate or a regular
  one,
- whether requirement for a given functionality has been declared in the
  widget's config.xml file (usually in form of a <feature> tag).


Description of the Security Model
=================================

Each DOM object is part of a single DOM environment. Each DOM environment is
assigned a single trust domain. A trust domain is a set of security rules. Each
security rule corresponds to a property on a DOM object (identified by a string)
and the kind of permission for the given property.
The security rule's permission decides whether the operation is allowed,
disallowed or a more complex action is required (asking the user, checking
feature declaration etc).

For each access attempt a security rule is matched based on the trust domain and
DOM property and the rule's permission is excercised.

Lack of security rule for a given operation means that the operation is allowed,
therefore all the predefined or user-defined properties work as expected.


Security Rule Identifiers
-------------------------

Each security rule is identified by a string. Identifiers must be unique within
a trust domain.
Security manager doesn't put any other restrictions on their form.


In practice, for easy integration with the DOM module, the identifiers are of
the form:

<object_name>.<property_name>

e.g.: AddressBookItem.update

This form allows the identifiers to be built in a generic way.


Features
--------

Features are groups of functionalities. In this context a feature may also be
described as a set of DOM objects and functions.

Features are declared in widgets' config.xml files with the <feature> tag. The
tag has a mandatory name property (an URI) that uniquely identifies the feature.

The main purpose for the features is to enable only these objects that
constitute features requested by the widget and save memory on those that are
not needed.

JIL widgets use them also as part of the security mechanism - functionality not
being part of any declared feature must not be allowed (this is mainly due to
poor mapping of DOM objects to features, espiecially in the JIL 1.0 and 1.1
versions).

The security model contains a mapping of security rule identifiers to feature
URIs that they required. Currently there are two such mappings: one for JIL 1.0
and 1.1 versions and the regular one for all other widgets (including JIL 1.2).

When a security decision needs to be made and the security rule needs a feature,
the appropriate feature mapping is consulted to find the feature URI for the
given security rule.
If the URI is declared in the widget's config.xml file, the operation is
permitted (provided that other checks are also positive).

Note: it is not necessary to provide feature mapping for all security rules for
objects that are never created in DOM unless their feature is declared.


Choice Persistence
------------------

In many cases it is the user who is asked to approve the given operation. In
order for the user not to be overwhelmed by dozens of dialogs, it is possible
for him/her to save the choice.

Depending on permissions assigned to security rule, the choice is one or more
of:
- NONE - ask once,
- RUNTIME - save for the given document,
- SESSION - save for session,
- FULL - save for ever.

The meanings of them may vary a bit for different environments.

In case of regular documents, the SESSION and FULL mean that the persisted
choice is also used for other documents opened in other tabs/windows.

If the environment is associated with a widget the choice is never shared with
other widgets and there is no difference between RUNTIME and SESSION (they both
mean 'as long as the widget is running'). The FULL persistence means that the
choice is saved with the widget's preferences and stored until the widget is
removed.


Properties vs. Functions
------------------------

Function invocation is usually a two-step process: access the property that
holds the function object and call the function.
For consistency functions and properties use the same format for naming the
security rules.

In order to avoid asking the user twice (once for property access, second time
for function invocation) a different permission types are used for functions
than for properties. In other words for each permission that requires user
interaction there are actually two permission type values, one for property
access and one for function invocation.


Notes
-----

The security checks must be performed in an asynchronous way because user
interaction is involved.

There is nothing in this security model that would prevent it from being used
by other parts of Opera than EcmaScript/DOM - the security rules don't have to
correspond to DOM properties.


Glossary
========

execution environment - an environment in which a particular operation is to be
performed. It is a very general concept. In practice it usually is bound to a
widget or JavaScript execution environment but that is not a requirement.

feature - a set of functionalities (JavaScript objects and functions) that is
enabled by appropriate <feature> tag in widget's config.xml.

permission type - type of behaviour assigned to a security rule. It may be
simple ("always allow") or complex ("ask the user once per session and make sure
appropriate feature is enabled").

security rule - defines permission type for a given operation. It is identified
by a name (usually corresponding to the property being accessed) and is assigned
to a trust domain.

trust domain - a set of rules corresponding to the current execution
environment. Each environment may belong to only one trust domain.


Changelog
=========

- 2010-01-05 - the initial version
