User Prompt Service Overview

Purpose

An application requests a service. The service provider (a system server) requests a decision from the UPS. The UPS searches for a matching policy file and policy. Based on the policy for the service, the service request may be immediately accepted or denied or it may need to receive a decision from the user, in which case it is accepted or denied after several further steps are carried out.

Device creators can customize the circumstances under which prompts are generated by configuring policies. Policies are made up of details about the service being requested as well as information about whether to accept or deny silently or to ask the user. They are defined in policy lists. Each service has one policy list defining any number of policies. In cases where the policy specifies that a user prompt is required, ECom plug-ins called Policy Evaluators and Dialog Creators, written by device creators.

Key concepts

The component has the following key concepts:

Policy

Policies specify whether application requests to access services should be processed silently or whether the user should be prompted for a decision. Policies may be general or specific – for example a policy may be specific to a single application, a group of applications or a class of applications (For example, those with unprotected secure ids). Policies are defined in policy lists. Device creators define policies.

UPS policy file

A UPS policy file is a compiled resource file containing all of the policies for a given service. The policies are ordered from most specific to least specific.

Because policies are matched in order, each service may have only one policy file. To define a policy safely, you need to know which other policies have been defined. If you place a general policy near the beginning of the list of policies, you prevent other policies from being evaluated.

Policy evaluator

Policy evaluators are Ecom plug-ins, which are responsible for generating fingerprints (see below) used to locate previous decision records related to the request. Device creators define policy evaluators.

Dialog creator

Dialog creators are Ecom plug-ins, which display and generate dialog prompts. Device creators define dialog creators.

Fingerprint

A fingerprint is a collection of data to do with the service being requested. The fingerprint usually includes the destination string supplied by the service that is matched to the destination string of a policy in the policy file. It might be a phone number, domain name, access point etc. A fingerprint is used to search the decision database for a match and to add a record to the decision database if a match was not found in the initial search. Device creators define the GenerateFingerprints() function in the Policy Evaluator plug-in.

A fingerprint serves two purposes:

• The UPS uses it to search the decision database for a match.

• If the UPS finds no record of a previous user decision and the user selects "always" or "never" in response to the UPS prompt, it uses the fingerprint to create a new record in the decision database.

It is possible to specify one or many policy evaluators. It is also possible not to specify a policy evaluator and to depend on the default policy evaluator.

Decision database

A decision database stores the phone user's choice of whether a request is always granted or never granted. Decisions stored in the decision database persist across reboots of the device. The decision database is provided by Symbian.

The decision database may not be accessed directly. However, records may be retrieved and deleted via the management APIs. This might be used by a control-panel application.

Architectural relationships

The UPS provides CDialogCreator and CPolicyEvaluator interfaces for device creators to implement.

Figure 1. UPS components

API summary

The following diagram shows the relationships between some of the key classes in the UPS.

Figure 2. Class diagram of key classes in UPS

Typical uses

The following diagram shows the sequence of activities performed by the UPS after it receives a request from a server:

Figure 3. Diagram showing activities for a single request

As is shown in the above diagram, the UPS returns a decision to the system server as in the following use cases:

• processing silently

• finding a stored decision in the decision database

• prompting the user in a dialog and resulting in a "one-shot" or "session" (non-persistent) decision by the user

• prompting the user in a dialog and resulting in an "always" or "never" (persistent) decision by the user

The Policy Evaluator allows device creators to customize the behaviour of the UPS at run-time. Policy Evaluators may:

• Allow security decisions to be specific to the data on which the service acts instead of simply granting full access to the service, for example "Allow application X to send SMS messages to 01234567". This is supported via the fingerprint functionality.

• Allow a security decision to be specific to an individual script executing within a scripting host. This is supported via the client entity field.

• Allow a prompt to be displayed even if the user selected "Always" or "Never". This could be based on a usage threshold or simply as additional confirmation if the user selected "Never". This is supported via the force prompt functionality.

Typical uses

The UPS component provides interfaces to perform the following tasks:

• Integrating a System Server with UPS

• Writing a UPS Policy File

• Writing a UPS Policy Evaluator

• Writing a UPS Dialog Creator

• Using UPS management APIs

• Example code at \sf\os\security\authorisation\userpromptservice\examples\ location.

See also

For related information, see UPS Configuration.