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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

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

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

    14 <section><title>Policies resource structure</title> <p>A policy resource is

    15 made up of the following; a header, followed by any number of policies. Policies

    16 need to be ordered from most specific to least specific. </p> <p>There are

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

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

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

    20 except <codeph>EAlwaysCheck</codeph>, prompts will not be generated for Messaging

    21 Server, Java VM etc because these components are in the ROM, have the appropriate

    22 capabilities and have protected secure ids. </p> </li>

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

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

    25 specific policy that always allows requests from trusted components as in

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

    27 </ul> </section>

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

    29 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

    30 existing decision records for services corresponding to the policy file are

    31 deleted or preserved when the policy file is upgraded. </p> <p>The <codeph>authorisationpolicy</codeph> field

    32 determines whether a system server must request authorisation from the User

    33 Prompt Service even if the client application passed the system server's security

    34 check. The value for <codeph>authorisationpolicy</codeph> can be one of the

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

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

    37 <tbody>

    38 <row>

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

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

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

    42 </row>

    43 <row>

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

    45 <entry><p>For application executables with a protected SID launched from the

    46 Z drive, where the system server checks have passed, allow the request. Otherwise

    47 call the UPS which may still choose to allow the request. For all other executables,

    48 ignore the system server (platsec) checks and always ask the UPS what to do. </p> </entry>

    49 </row>

    50 <row>

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

    52 <entry><p>For application executables with a protected SID (regardless of

    53 drive), where the system server checks have passed, allow the request. Otherwise

    54 call the UPS which may still choose to allow the request. For all other executables,

    55 ignore the system server (platsec) checks, and always ask the UPS what to

    56 do. </p> </entry>

    57 </row>

    58 <row>

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

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

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

    62 </row>

    63 <row>

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

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

    66 server checks failed, reject the request. Never query the UPS – just use existing

    67 security check result implemented by system server. (This is the legacy pre-UPS

    68 behaviour.) </p> </entry>

    69 </row>

    70 </tbody>

    71 </tgroup>

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

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

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

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

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

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

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

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

    80 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

    81  {

    82  // The major version number of THIS policy file.

    83  // When policy files are upgraded or eclipsed the UPS deletes all decision

    84  // records for the system server server SID and service ID where the major

    85  // version in the decision record is not equal to the major version

    86  // number in the policy file.

    87  majorversion = 0;

    88  // The minor version number of THIS policy file.

    89  minorversion = 0; 

    90 

    91  // Built-in (protected SID and loaded from Z drive) client applications

    92  // do not require authorisation from the UPS if the client has the correct

    93  // capabilities.

    94  authorisationpolicy = ECheckPostManufacture;

    95  //dialogcreator and policyevaluator UIDs

    96  dialogcreator = 0x10283694;

    97  policyevaluator = 0x10283698;

    98  };

    99 </codeblock> </section>

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

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

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

   103 <tbody>

   104 <row>

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

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

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

   108 </row>

   109 <row>

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

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

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

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

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

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

   116 </row>

   117 <row>

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

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

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

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

   122 </row>

   123 <row>

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

   125 <entry><p>Allows policies to be matched according to whether the client process

   126 passed the security check defined by the system server. Typically, this corresponds

   127 to whether the client has the correct capabilities for the requested service.

   128 However, system servers are free to use features other than capabilities in

   129 their security check. </p> </entry>

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

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

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

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

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

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

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

   137 </row>

   138 <row>

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

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

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

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

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

   144 </row>

   145 <row>

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

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

   148 <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

   149 is likely that a system server will define a session to be the life-time of

   150 the client process. Consequently, the client application would have to be

   151 restarted in order to gain access to the service. This makes it difficult

   152 to write a well-behaved application that switches between on-line and off-line

   153 modes. </p> <p>(Defined in ups/policies.rh.) </p> </entry>

   154 </row>

   155 <row>

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

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

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

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

   160 </row>

   161 <row>

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

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

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

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

   166 </row>

   167 <row>

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

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

   170 behaviour. </p> </entry>

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

   172 </row>

   173 </tbody>

   174 </tgroup>

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

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

   177 the request. If the matched policy defines only negative <codeph>options</codeph> (No

   178 or Never), the UPS silently instructs the system server to reject the request.

   179 It is usually better not to configure UPS policies to silently reject requests

   180 because it is likely to cause the client application to fail without warning.

   181 Instead, the policy could restrict requests to one-shot permissions (Yes or

   182 No). </p> </section>

   183 <section><title>Matching policies </title> <p>The UPS compares each policy

   184 within a file in order, starting with the first policy in the file, against

   185 the incoming request until a match is found. The match is based on the secure

   186 id of the client application, the destination of the request (e.g. Phone number,

   187 Access Point) and whether the client passed the system server's platform security

   188 check. All three elements must match (wildcards are supported) the data in

   189 the request before the policy is considered a match. </p> <p>You can use the <codeph>sid_list</codeph> and <codeph>destination</codeph> fields

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

   191 specific destinations, such as one telephone number, in <codeph>destination</codeph>. </p> <p>Because

   192 the UPS compares incoming requests against policies in order, the UPS requires

   193 that all of the policies for a given service are ordered from most specific

   194 to least specific in a single policy file. Only the first policy that matches

   195 is evaluated. So if, for example, you need to provide specific behaviour for

   196 one application that falls into the category <codeph>KProtectedSids</codeph> as

   197 well as providing more general behaviour for all other applications falling

   198 into the <codeph>KProtectedSids</codeph> category, you need to define the

   199 policy for the individual application first. Likewise, if you need to provide

   200 behaviour for one particular destination but another behaviour for all other

   201 destinations, you need to specify the policy for the specific destination

   202 first. </p></section>

   203 <section><title>Default policies</title> <p>If a UPS policy

   204 file exists for a system server/service but no policy matches the request,

   205 the UPS internally creates a default policy object that is passed to the Policy

   206 Evaluator and Dialog Creator. This policy object allows one-shot permissions

   207 for applications, which will already have got past the platform security check.

   208 Policy file authors may override this by defining a generic policy to match

   209 all requests at the end of the policy file. </p></section>

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

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

   212 </conbody></concept>