Symbian3/PDK/Source/GUID-6849E256-6719-5788-BCB2-7557F09AAAD0.dita
author Dominic Pinkman <Dominic.Pinkman@Nokia.com>
Fri, 22 Jan 2010 18:26:19 +0000
changeset 1 25a17d01db0c
child 3 46218c8b8afa
permissions -rw-r--r--
Addition of the PDK content and example code for Documentation_content according to Feature bug 1607 and bug 1608

<?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-6849E256-6719-5788-BCB2-7557F09AAAD0" xml:lang="en"><title>UPS
Configuration</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>User Prompt Service (UPS) configuration component (<codeph>\securityconfig\ups\</codeph>)
includes a <filepath>backup.xml</filepath> file and a ROM stub SIS file for
configuring a UPS policy file. Device creators must modify the configuration
files of UPS and rebuild the <filepath>securityconfig</filepath> component,
to customise the behavior of the UPS component. </p>
<section><title> Introduction</title> <p>UPS policy files are resource files
that specify whether application requests to access services are silently
accepted or denied or whether they require the user to be prompted. Each service
has a policy file. The policy file lists policies for various applications.
The configuration of policy file involves configuring ROM stub package file
and backup XML file.  </p> </section>
<section><title> Installing and Configuring UPS Policy file</title> <p><b>Installing
policy files</b> </p> <p>A policy file on the system drive eclipses a policy
file on the Z drive if it has the same filename. If the policy file on the
system drive is corrupt, the policy file on the Z drive (if it exists) is
used instead. The policy files should be installed (and upgraded) through
Software Install to the private directory of the UPS on the system drive.
The private directory is <filepath>\private\10283558\policies</filepath>. </p> <p><b>Upgrading
package file</b> </p> <p>The SIS file must either contain the executable or
be an upgrade to the base package which supplied the executable, for delivering
files into the private directory of an executable. </p> <p>The following is
a default implementation of a package file for UPS server ROM stub SIS file: </p> <codeblock id="GUID-51117852-B051-5E7F-8216-44A8B7EFF6A1" xml:space="preserve">; Package file for User Prompt Service server ROM stub SIS file
;
; A ROM stub SIS file is required to allow UPS policy files to be
; provisioned post-manufacture because policy files are loaded from
; the policies subdirectory of the UPS server's private directory.

&amp;EN

#{"User Prompt Service"}, (0x10285777), 1, 0 , 0, TYPE=SA

%{"Nokia Corporation and/or its subsidiary(-ies)"}
:"Nokia Corporation and/or and/or its subsidiary(-ies)"

; UPS policy files on the Z drive must also be included here if
; upgrades (eclipsing) is required post-manufacture.

""-"z:\sys\bin\upsserver.exe"
</codeblock> <p>Device creators must create a ROM stub SIS file if they want
to allow policy files to be delivered after-market (since the UPS server is
delivered in the ROM). </p> <note>To ensure that policy file upgrades are
approved by manufacturers or Symbian Signed, SIS files that modify the private
directory of the UPS must be signed by a certificate where CA has the <codeph>AllFiles</codeph> capability. </note> <p><b>Verifying
hash of the policy</b> </p> <p>The <codeph>VERIFY</codeph> option must be
added to the line in the package file that installs the UPS policy file to
ensure that the Software Install checks the hash of the policy at restore
time. The following sample package file uses the <codeph>VERIFY</codeph> flag. </p> <codeblock id="GUID-E62C7BEF-A0C8-5BD2-B011-2E1ED211FE61" xml:space="preserve">; tupspolicies1.pkg
;
; 

; Checks the installation of UPS policies files

&amp;EN
#{"UPS Policy Files"}, (0x10285777), 1, 0, 0, TYPE=SP
%{"Symbian Foundation"}
:"Symbian Foundation"

; The VERIFY option is used to flag the files as non-modifiable so that SWI
; checks the hashes during restore

"data\ups_01041000_01041001.rsc"-"$:\private\10283558\policies\ups_01041000_01041001.rsc", VERIFY
"data\ups_01041000_01041002.rsc"-"$:\private\10283558\policies\ups_01041000_01041002.rsc", VERIFY
"data\ups_01042000_01042001.rsc"-"$:\private\10283558\policies\ups_01042000_01042001.rsc", VERIFY
"data\ups_01043000_01043001.rsc"-"$:\private\10283558\policies\ups_01043000_01043001.rsc", VERIFY
</codeblock><note><ul>
<li><p>Version 5.1.0.1 or higher of makesis should be used because the VERIFY
flag is not supported in older versions.  </p></li>
<li><p>The major and minor versions field in the policy header of the policy
file can be used to provide information that is used in upgrades. If the major
version number is changed when a policy file is upgraded, all decision records
for that policy file are deleted (because the major version number is stored
in the decision record). </p></li>
<li><p>Upgrading the plug-ins does not delete the decision records. If device
creators want to delete decision records with a plug-in upgrade they must
either update associated policy files or provide a run-on-install executable
that calls the management API to delete decision records. </p></li>
</ul></note> <p><b>Back up and restoring</b> </p> <p>UPS policy files may
be backed up and restored providing that a valid <filepath>backup.xml</filepath> file
is provided. The following is a sample backup file provided by Symbian. </p> <codeblock id="GUID-3BFD715C-68FB-5F87-9557-DB95D18168FB" xml:space="preserve">&lt;?xml version="1.0" standalone="yes" ?&gt;
- &lt;backup_registration&gt;
- &lt;passive_backup&gt;
  &lt;include_directory name="policies" /&gt;
  &lt;/passive_backup&gt;
  &lt;restore requires_reboot="no" /&gt;
  &lt;/backup_registration&gt;
</codeblock> </section>
</conbody></concept>