Policy Resource

Policies resource structure

A policy resource is made up of the following; a header, followed by any number of policies. Policies need to be ordered from most specific to least specific.

There are two ways to control whether prompts are generated for system servers:

  • Using the authorisationpolicy setting in the header. If authorisationpolicy is set to anything except EAlwaysCheck, prompts will not be generated for Messaging Server, Java VM etc because these components are in the ROM, have the appropriate capabilities and have protected secure ids.

  • Using the SID_LIST setting in the policy. The SID_LIST can be used to create a very specific policy that always allows requests from trusted components as in the example policy below.

Header

The header includes the following possible fields: majorversion, minorversion, authorisationpolicy, dialogcreator and policyevaluator.

The major version number controls whether existing decision records for services corresponding to the policy file are deleted or preserved when the policy file is upgraded.

The authorisationpolicy field determines whether a system server must request authorisation from the User Prompt Service even if the client application passed the system server's security check. The value for authorisationpolicy can be one of the following:

EAlwaysCheck

Ignore the system server (platsec) checks and always ask the UPS what to do.

ECheckPostManufacture

For application executables with a protected SID launched from the Z drive, where the system server checks have passed, allow the request. Otherwise call the UPS which may still choose to allow the request. For all other executables, ignore the system server (platsec) checks and always ask the UPS what to do.

ECheckUnprotectedSids

For application executables with a protected SID (regardless of drive), where the system server checks have passed, allow the request. Otherwise call the UPS which may still choose to allow the request. For all other executables, ignore the system server (platsec) checks, and always ask the UPS what to do.

ECheckIfFailed

If the system server checks passed, allow the request. If they failed, call the UPS which may still choose to allow the request.

ENeverCheck

If the system server checks passed, allow the request. If the system server checks failed, reject the request. Never query the UPS – just use existing security check result implemented by system server. (This is the legacy pre-UPS behaviour.)

If no authorisationpolicy is provided, the default is ECheckPostManufacture.

Note: If a policy file is not defined for a system server or service then a default value of ENeverCheck is used.

The dialogcreator must be provided and must not be zero. In the policy file it is the only field that is actually required. The policyevaluator can be specified here, but if one is not specified, a default policy evaluator is called. The dialogcreator and policyevaluator UIDs are allocated by Symbian Signed. They are the implementation UIDs of the relevant ECOM plugins.

The following shows an example header:

header = POLICY_HEADER
 {
 // The major version number of THIS policy file.
 // When policy files are upgraded or eclipsed the UPS deletes all decision
 // records for the system server server SID and service ID where the major
 // version in the decision record is not equal to the major version
 // number in the policy file.
 majorversion = 0;
 // The minor version number of THIS policy file.
 minorversion = 0; 

 // Built-in (protected SID and loaded from Z drive) client applications
 // do not require authorisation from the UPS if the client has the correct
 // capabilities.
 authorisationpolicy = ECheckPostManufacture;
 //dialogcreator and policyevaluator UIDs
 dialogcreator = 0x10283694;
 policyevaluator = 0x10283698;
 };

Policies

Policies can have the following optional fields:

Field

Description

Possible values

sid_classes

A bitmask that defines the set of SID classes that this policy applies to. It is ignored if a sid_list[] field is provided.

KProtectedSids (All clients with a protected SID) KUnprotectedSids (All clients with an unprotected SID) KAllSids (All clients)

(Defined in ups/policies.rh.)

sid_list[]

An array of LONGs that defines a set of specific client application SIDs that this policy applies to.

<Application SID>, <Application SID>, …

systemserversecurity

Allows policies to be matched according to whether the client process passed the security check defined by the system server. Typically, this corresponds to whether the client has the correct capabilities for the requested service. However, system servers are free to use features other than capabilities in their security check.

ESystemServerSecurityPassedOrFailed (The policy applies regardless of whether the client process passed the system server's security check.)

ESystemServerSecurityFailed (The policy only applies if the client process failed the system server's security check.)

ESystemServerSecurityPassed (The policy only applies if the client process passed the system server's security check.)

(Defined in ups/policies.rh.)

destination

A string to match against the destination supplied by system server.

“<STRING>” (e.g. telephone number) or “*” for all (The default value is "*" and the matching rules are those of TDesC::MatchF, so it is a case-insensitive wildcard match.)

options

A bit field to control which buttons to display on the dialog.

KYes, KNo, KSessionYes, KAlways, KNever, KSessionNo

KSessionNo should be used with care because it is likely that a system server will define a session to be the life-time of the client process. Consequently, the client application would have to be restarted in order to gain access to the service. This makes it difficult to write a well-behaved application that switches between on-line and off-line modes.

(Defined in ups/policies.rh.)

policyevaluator

If non-zero, overrides the implementation UID of the policy evaluator defined in the header.

<UID>

dialogcreator

If non-zero, overrides the implementation UID of the dialog creator defined in the header.

<UID>

flags

Flags specific to the policy evaluator. Can be used to trigger specific behaviour.

<16-bit number>

Note: If the matched policy defines only positive options (Yes, Session or Always), the UPS silently instructs the system server to allow the request. If the matched policy defines only negative options (No or Never), the UPS silently instructs the system server to reject the request. It is usually better not to configure UPS policies to silently reject requests because it is likely to cause the client application to fail without warning. Instead, the policy could restrict requests to one-shot permissions (Yes or No).

Matching policies

The UPS compares each policy within a file in order, starting with the first policy in the file, against the incoming request until a match is found. The match is based on the secure id of the client application, the destination of the request (e.g. Phone number, Access Point) and whether the client passed the system server's platform security check. All three elements must match (wildcards are supported) the data in the request before the policy is considered a match.

You can use the sid_list and destination fields to fine-tune your policies, by providing specific application UIDs in sid_list and specific destinations, such as one telephone number, in destination.

Because the UPS compares incoming requests against policies in order, the UPS requires that all of the policies for a given service are ordered from most specific to least specific in a single policy file. Only the first policy that matches is evaluated. So if, for example, you need to provide specific behaviour for one application that falls into the category KProtectedSids as well as providing more general behaviour for all other applications falling into the KProtectedSids category, you need to define the policy for the individual application first. Likewise, if you need to provide behaviour for one particular destination but another behaviour for all other destinations, you need to specify the policy for the specific destination first.

Default policies

If a UPS policy file exists for a system server/service but no policy matches the request, the UPS internally creates a default policy object that is passed to the Policy Evaluator and Dialog Creator. This policy object allows one-shot permissions for applications, which will already have got past the platform security check. Policy file authors may override this by defining a generic policy to match all requests at the end of the policy file.