<?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-85D9878E-4FEF-5E45-9F87-53634CD171E0" xml:lang="en"><title>Integrating

a System Server with UPS</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Introduction</title> <p>User Prompt Service (UPS) functionality

is provided by the server process <filepath>upsserver.exe</filepath>. The

process starts on demand when system servers make calls to the UPS client

library. Only applications with a capability of <codeph>ProtServ</codeph> or

higher can access <filepath>upsserver.exe</filepath>. </p> <p>A system server

should only invoke the UPS for security decisions that a typical phone user

will understand (For example, it is inappropriate to ask the user for permission

to change a low level network setting.) . </p> <p>Device creators can write

a system server that invokes the UPS, if a compatible dialog creator is available

and the policies are delivered in an appropriately signed SIS file. They can

also write a policy evaluator, but a default policy evaluator is provided

by Symbian platform. </p> <p>If the device creators do not specify any policy

file, the UPS uses the platform security check results to decide whether to

access requested services. Thus not supplying policy files effectively turns

UPS off. </p> </section>

<section><title>Required background</title><p id="GUID-9C6EBADD-175A-5122-90C4-CED8A9855BAB"><b>Configuring

the system server</b> </p> <p>For each system server that accesses the UPS,

you need to do the following: </p> <ol id="GUID-D14BDAE1-BD62-530E-B3C4-2FA380BDBDC5">

<li id="GUID-090CE65B-44BF-54CF-8961-69059655C5F5"><p>Create one <codeph>RUpsSession</codeph> per

server. </p> <p>Typically, an <codeph>RUpsSubession</codeph> object is created

for each connection by a client to the system server and can only have one

outstanding call to <xref href="GUID-1C63BE5E-6F66-38CB-931E-B2C51309CB74.dita#GUID-1C63BE5E-6F66-38CB-931E-B2C51309CB74/GUID-82C3C51A-F785-3DBA-910A-47CAF47B39F6"><apiname>RUpsSubsession::Authorise()</apiname></xref>. </p> </li>

<li id="GUID-61E4A569-F5C3-593C-9954-2803E822F0BF"><p> <xref href="GUID-1C63BE5E-6F66-38CB-931E-B2C51309CB74.dita#GUID-1C63BE5E-6F66-38CB-931E-B2C51309CB74/GUID-82C3C51A-F785-3DBA-910A-47CAF47B39F6"><apiname>RUpsSubsession::Authorise()</apiname></xref> completes

immediately and uses the result of its <codeph>aServerCheckOk</codeph> parameter

to set its <codeph>aDecision</codeph> parameter, if a policy file is not defined

for a service. Therefore, the default behaviour of an unconfigured UPS is

compatible with the existing platform security implementation. </p> </li>

<li id="GUID-035F2AEE-95B8-5085-9079-A4B8A6EC9B6A"><p>Close each <xref href="GUID-1C63BE5E-6F66-38CB-931E-B2C51309CB74.dita"><apiname>RUpsSubsession</apiname></xref>. </p> </li>

</ol><p id="GUID-75BD33B9-28AC-55CD-BF3E-7F62A8D039EB"><b>Considerations</b> </p> <p>Consider

the following points before integrating the UPS to a system server </p> <ul>

<li id="GUID-11A0A48F-47A3-5A89-9925-8FBAB3F5D8DE"><p>Even though the APIs

for the UPS are relatively small, the integration is slightly more complicated

than might be expected. This is because existing synchronous security checks

must become asynchronous since interaction with the device user is inherently

an asynchronous operation. For example, it would be undesirable to block the

entire comms server while waiting for the user to respond to a dialog. </p> </li>

<li id="GUID-747A3037-13E6-5895-895E-F700368A81B6"><p>Provide an informed

security decision the user may need to know about the request they are authorizing.

Consequently, it may be necessary to extract the parameters from the client

application at the security check stage. </p> </li>

<li id="GUID-27A11CBD-BBB5-5D32-8207-D01D207FEC9E"><p>Finally, depending on

the service and the security requirements of the manufacturer, an operator

user prompts may be in addition to the platform security (e.g. capabilities)

checks. Alternatively, user prompts could be used to allow applications without

capabilities limited access to a protected service. Because most implementations

of the <codeph>CPolicyServer</codeph> fail the client immediately if the platsec

check fails these checks may have to be modified. </p> </li>

</ul><p> <b>Note</b>: For an example of how to include the above, see the

example code later in this document. </p></section>

<section><title>Integration of UPS</title> <p>If the system server uses the <codeph>CPolicyServer</codeph> framework,

there are three candidates for the main integration point. </p> <table id="GUID-BBE389D8-77A0-52BA-910D-368BAC25DCC3">

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

<tbody>

<row>

<entry><p>Function </p> </entry>

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

</row>

<row>

<entry><p> <xref href="GUID-5BDFF5B1-DC1F-393A-879B-9D8DE080B4E2.dita#GUID-5BDFF5B1-DC1F-393A-879B-9D8DE080B4E2/GUID-49DDDDAC-B256-3B43-B059-EE369EAEA2BB"><apiname>CPolicyServer::CustomSecurityCheckL()</apiname></xref>  </p> </entry>

<entry><p>This allows an arbitrary and even asynchronous check to be made

instead of using static security policies. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-5BDFF5B1-DC1F-393A-879B-9D8DE080B4E2.dita#GUID-5BDFF5B1-DC1F-393A-879B-9D8DE080B4E2/GUID-93C9B0EE-8B94-3A95-BBA7-5B1C8BED6E28"><apiname> CPolicyServer::CustomFailureActionL()</apiname></xref>  </p> </entry>

<entry><p>This virtual method is invoked if the client fails the static security

checks. The failure may be overridden or deferred. Asynchronous operations

are possible. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-D5A30C75-E22C-34E8-913B-7D2CA6AD5C51.dita#GUID-D5A30C75-E22C-34E8-913B-7D2CA6AD5C51/GUID-B37413F7-D8FD-35AD-A037-99023D7CE986"><apiname> CSession2::ServiceL()</apiname></xref>  </p> </entry>

<entry><p>The static policy checks could be deferred until the session is

created provided that the server connection API is not guarded by user prompts. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>Use one or a combination of above functions as required to implement

UPS APIs </p><p><b>Procedure</b> </p> <p>This demonstrates how user permission

prompt support (UPS) may be added to a system server. </p> <ol id="GUID-BC8CDF54-101F-563E-BA74-7DE871A93782">

<li id="GUID-55A1C176-857B-539F-81F1-66FCDEDEF299"><p>An <codeph>RUpsSession</codeph> object

has been added to the <codeph>CMsgServer</codeph> class. This is initialized

at startup. </p> </li>

<li id="GUID-8DD68273-846D-568A-A7BE-330523722503"><p> <xref href="GUID-AB9191BA-9E9B-3ED8-9968-4E43C1803C0D.dita#GUID-AB9191BA-9E9B-3ED8-9968-4E43C1803C0D/GUID-6A3E9888-EA11-3352-A634-946C66A3946C"><apiname>CMsgServer::iPolicyElements</apiname></xref> was

changed to cause <codeph>CustomFailureActionL</codeph> to be invoked if the

static security policy check fails instead of failing the client. </p> </li>

<li id="GUID-C2AF0E9B-C46A-59E4-ADB7-21D2018582DD"><p> <xref href="GUID-AB9191BA-9E9B-3ED8-9968-4E43C1803C0D.dita#GUID-AB9191BA-9E9B-3ED8-9968-4E43C1803C0D/GUID-3498AEBD-A092-3D0B-98EB-50A1B9DC65B5"><apiname>CMsgServer::CustomFailureActionL()</apiname></xref> notifies

the session object that the platsec check failed. This is important because <xref href="GUID-1C63BE5E-6F66-38CB-931E-B2C51309CB74.dita#GUID-1C63BE5E-6F66-38CB-931E-B2C51309CB74/GUID-82C3C51A-F785-3DBA-910A-47CAF47B39F6"><apiname>RUpsSubsession::Authorise()</apiname></xref> requires

this information to allow unconfigured systems to be compatible with platsec.

It also increases the flexibility of the UPS policy definitions. </p> </li>

<li id="GUID-63A4E019-BDFF-5B37-993B-3ED8233EC781"><p>An <codeph>RUpsSubsession</codeph> instance

is created for each <codeph>CSession2</codeph> object, i.e. requests from

different clients are authorized independently. This could be modified so

that there is one UPS sub-session for each client process instead of each

connection from a client process. </p> </li>

<li id="GUID-82211891-BA54-501F-9E81-D6D78C4476E7"><p>An extra state (<codeph>iAuthorising</codeph>)

is added at the start of the CMsgProcessor state machine. </p> </li>

<li id="GUID-EC85BB4D-83B9-5AF0-9A19-818B6AD4CE6C"><p>The <codeph>RMessage2</codeph> parameters

from the client API are now extracted in the authorization stage to enable

the information to be passed to the UPS. </p> </li>

<li id="GUID-91D30A49-B703-5E01-BAC9-F9205DB9BAA2"><p> <xref href="GUID-C4092739-2792-3411-90CC-174398AE4A4C.dita#GUID-C4092739-2792-3411-90CC-174398AE4A4C/GUID-9DE31D77-70B7-3072-A602-75D995749DB3"><apiname>CMsgProcessor::DoCancel</apiname></xref> is

updated to cancel the call to <xref href="GUID-1C63BE5E-6F66-38CB-931E-B2C51309CB74.dita#GUID-1C63BE5E-6F66-38CB-931E-B2C51309CB74/GUID-06BF925F-53C1-33D4-97F3-46ECB10CC27F"><apiname>RUpsSubsession::Authorise</apiname></xref>,

if the client cancels the sending of the message or disconnects. </p> </li>

<li id="GUID-684BEA9C-B6F7-5369-A243-9D0689BBD421"><p> <xref href="GUID-C4092739-2792-3411-90CC-174398AE4A4C.dita#GUID-C4092739-2792-3411-90CC-174398AE4A4C/GUID-013B385A-2A30-36D6-990A-873CF329F9E7"><apiname>CMsgProcessor::RunL</apiname></xref> now

checks whether the request was authorized before changing from the authorization

to the sending state. </p> </li>

</ol> <p>The following code snippet explains how the UPS APIs can be called. </p> <codeblock id="GUID-1B2C7094-BFA3-5C49-ABDB-4721BC71D8CE" xml:space="preserve">

using namespace UserPromptService;

TUpsDecision AuthoriseL(RThread &aClientThread, TDesC aDestination)

    {

 // Create and connect the session.

 // In a real server this should be done once at server startup as it is a relatively

 // expensive operation.

 RUpsSession session;

 User::LeaveIfError(session.Connect());

 CleanupClosePushL(session);

 // Initialise the subsession

 // One of these is required per a concurrent Authorise request.

 // Note that it only connects to the UPS if it has to.

    RUpsSubsession subsession;

 subsession.Initialise(session, aClientThread);

 CleanupClosePushL(subsession);

 TServiceId serviceId = {43};

 // Out "service id", typically a constant

 // Variable for the result, typically a member variable because it must exist until

 // the Authorise request completes.

 TUpsDecision decision = EUpsDecYes;

 // Issue the Authorise request

 TRequestStatus rs;

 subsession.Authorise(EFalse, // Did out platsec checks pass?

                         serviceId, 

                         aDestination, 

                         decision, 

                         rs); // Would typically be the iStatus of a CActive object

    // Wait for the request to complete

 User::WaitForRequest(rs);

 CleanupStack::PopAndDestroy(&subsession);

 CleanupStack::PopAndDestroy(&session);

 return decision;

 }

TInt E32Main()

 {

 __UHEAP_MARK;

 // allocating a cleanup stack also installs it

 CTrapCleanup* tc = CTrapCleanup::New();

 if (tc == 0)

  return KErrNoMemory;

 RThread thd;

 TRAPD(err, AuthoriseL(thd, _L("destination")));

 if(err != KErrNone)

  {

  User::Panic(_L("example failed: "), err);

  }

 delete tc;

 __UHEAP_MARKEND;

 return KErrNone;

 }

</codeblock> </section>

</conbody></concept>