<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-4E838A77-C7B5-5B1F-93F5-F3577901914B" xml:lang="en"><title>Policy

Resource </title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Policies resource structure</title> <p>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. </p> <p>There are

two ways to control whether prompts are generated for system servers: </p> <ul>

<li id="GUID-99E2B7E8-5FA0-5A55-ADE9-D832C4A6CF3C"><p>Using the <codeph>authorisationpolicy</codeph> setting

in the header. If <codeph>authorisationpolicy</codeph> is set to anything

except <codeph>EAlwaysCheck</codeph>, 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. </p> </li>

<li id="GUID-E8B43077-ECC9-5D4F-A613-B168058E0162"><p>Using the <codeph>SID_LIST</codeph> setting

in the policy. The <codeph>SID_LIST</codeph> can be used to create a very

specific policy that always allows requests from trusted components as in

the example policy below. </p> </li>

</ul> </section>

<section><title>Header </title> <p>The header includes the following possible

fields: <codeph>majorversion</codeph>, <codeph>minorversion</codeph>, <codeph>authorisationpolicy</codeph>, <codeph>dialogcreator</codeph> and <codeph>policyevaluator</codeph>. </p> <p>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. </p> <p>The <codeph>authorisationpolicy</codeph> 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 <codeph>authorisationpolicy</codeph> can be one of the

following: </p> <table id="GUID-45D126E1-1CF1-59AF-A438-AB252BC49A4D">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <codeph>EAlwaysCheck</codeph>  </p> </entry>

<entry><p>Ignore the system server (platsec) checks and always ask the UPS

what to do. </p> </entry>

</row>

<row>

<entry><p> <codeph>ECheckPostManufacture </codeph>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

<row>

<entry><p> <codeph>ECheckUnprotectedSids</codeph>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

<row>

<entry><p> <codeph> ECheckIfFailed</codeph>  </p> </entry>

<entry><p>If the system server checks passed, allow the request. If they failed,

call the UPS which may still choose to allow the request. </p> </entry>

</row>

<row>

<entry><p> <codeph> ENeverCheck</codeph>  </p> </entry>

<entry><p>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.) </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>If no <codeph>authorisationpolicy</codeph> is provided, the default

is <codeph>ECheckPostManufacture</codeph>. </p> <p> <b>Note</b>: If a policy

file is not defined for a system server or service then a default value of <codeph>ENeverCheck</codeph> is

used. </p> <p>The <codeph>dialogcreator</codeph> must be provided and must

not be zero. In the policy file it is the only field that is actually required.

The <codeph>policyevaluator</codeph> can be specified here, but if one is

not specified, a default policy evaluator is called. The <codeph>dialogcreator</codeph> and <codeph>policyevaluator</codeph> UIDs

are allocated by Symbian Signed. They are the implementation UIDs of the relevant

ECOM plugins. </p> <p>The following shows an example header: </p> <codeblock id="GUID-C626C28A-9121-5AC6-B075-C3EE939C3DC1" xml:space="preserve">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;

 };

</codeblock> </section>

<section><title> Policies</title> <p>Policies can have the following optional

fields: </p> <table id="GUID-5CB991E2-1268-5D07-BF99-585F6DC2C5A3">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<tbody>

<row>

<entry><p> <b> Field</b>  </p> </entry>

<entry><p> <b>Description</b>  </p> </entry>

<entry><p> <b>Possible values </b>  </p> </entry>

</row>

<row>

<entry><p> <codeph>sid_classes </codeph>  </p> </entry>

<entry><p>A bitmask that defines the set of SID classes that this policy applies

to. It is ignored if a <codeph>sid_list[]</codeph> field is provided. </p> </entry>

<entry><p> <codeph>KProtectedSids</codeph> (All clients with a protected SID) <codeph>KUnprotectedSids</codeph> (All

clients with an unprotected SID) <codeph>KAllSids</codeph> (All clients) </p> <p>(Defined

in ups/policies.rh.) </p> </entry>

</row>

<row>

<entry><p> <codeph> sid_list[] </codeph>  </p> </entry>

<entry><p>An array of LONGs that defines a set of specific client application

SIDs that this policy applies to. </p> </entry>

<entry><p>&lt;Application SID&gt;, &lt;Application SID&gt;, … </p> </entry>

</row>

<row>

<entry><p> <codeph>systemserversecurity</codeph>  </p> </entry>

<entry><p>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. </p> </entry>

<entry><p> <codeph> ESystemServerSecurityPassedOrFailed</codeph> (The policy

applies regardless of whether the client process passed the system server's

security check.) </p> <p> <codeph>ESystemServerSecurityFailed</codeph> (The

policy only applies if the client process failed the system server's security

check.) </p> <p> <codeph>ESystemServerSecurityPassed</codeph> (The policy

only applies if the client process passed the system server's security check.) </p> <p>(Defined

in ups/policies.rh.) </p> </entry>

</row>

<row>

<entry><p> <codeph> destination</codeph>  </p> </entry>

<entry><p>A string to match against the destination supplied by system server. </p> </entry>

<entry><p>“&lt;STRING&gt;” (e.g. telephone number) or “*” for all (The default

value is "*" and the matching rules are those of <codeph>TDesC::MatchF</codeph>,

so it is a case-insensitive wildcard match.) </p> </entry>

</row>

<row>

<entry><p> <codeph> options</codeph>  </p> </entry>

<entry><p>A bit field to control which buttons to display on the dialog. </p> </entry>

<entry><p> <codeph>KYes</codeph>, <codeph>KNo</codeph>, <codeph>KSessionYes</codeph>, <codeph>KAlways</codeph>, <codeph>KNever</codeph>, <codeph>KSessionNo</codeph>  </p> <p> <codeph>KSessionNo</codeph> 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. </p> <p>(Defined in ups/policies.rh.) </p> </entry>

</row>

<row>

<entry><p> <codeph>policyevaluator </codeph>  </p> </entry>

<entry><p>If non-zero, overrides the implementation UID of the policy evaluator

defined in the header. </p> </entry>

<entry><p>&lt;UID&gt; </p> </entry>

</row>

<row>

<entry><p> <codeph> dialogcreator </codeph>  </p> </entry>

<entry><p>If non-zero, overrides the implementation UID of the dialog creator

defined in the header. </p> </entry>

<entry><p>&lt;UID&gt; </p> </entry>

</row>

<row>

<entry><p> <codeph> flags</codeph>  </p> </entry>

<entry><p>Flags specific to the policy evaluator. Can be used to trigger specific

behaviour. </p> </entry>

<entry><p>&lt;16-bit number&gt; </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p> <b>Note</b>: If the matched policy defines only positive <codeph>options</codeph> (Yes,

Session or Always), the UPS silently instructs the system server to allow

the request. If the matched policy defines only negative <codeph>options</codeph> (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). </p> </section>

<section><title>Matching policies </title> <p>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. </p> <p>You can use the <codeph>sid_list</codeph> and <codeph>destination</codeph> fields

to fine-tune your policies, by providing specific application UIDs in <codeph>sid_list</codeph> and

specific destinations, such as one telephone number, in <codeph>destination</codeph>. </p> <p>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 <codeph>KProtectedSids</codeph> as

well as providing more general behaviour for all other applications falling

into the <codeph>KProtectedSids</codeph> 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. </p></section>

<section><title>Default policies</title> <p>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. </p></section>

<section><title>See also</title> <p> <xref href="GUID-DB827750-6057-537E-8FE1-8F68BF2E9F99.dita">Writing

the UPS Policy File</xref>  </p> </section>