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.