//

// Copyright (c) Symbian Software Ltd 2007. All rights reserved.

//

*** Overview ***

This directory contains example code that demonstrates how user permission

prompt support(UPS) may be added to a system server. The example code consists of

three components.

*** Components ***

1) tmsgserver 

A simple server that provides an asynchronous API to send messages. Since this

is example code the messages are displayed to the screen.

2) tmsclient 

The client library for tmsgserver.  

No modifications are necessary in order to support user permission prompts.

3) tmsgapp

An example application that sends a number of messages and also tests cancellation. 

No modification was required as a consequence of the UPS integration. However,

in order to allow the test to be run multiple times the UPS management API is

used to delete old decision records for this application.

*** Integration Overview *** 

Whilst the APIs for the UPS are relatively small the integration is slightly

more complicated than might be expected 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 network server whilst waiting for the user to respond to a

dialog.

The second factor that must be considered is that in order to make an informed

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

authorizing. Consequently, it may be necessary to extract the parameters from

the client application at the security check stage.

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. Since most implementations of the CPolicyServer fail the client

immediately if the platsec check fails these checks may have to be modified.

*** Integration Points *** 

If the system server uses the CPolicyServer framework then there are three

candidates for the main integration point.

1) CPolicyServer::CustomSecurityCheckL

This allows an arbitrary and even asynchronous check to be made instead of using

static security policies.

2) CPolicyServer::CustomFailureActionL

This virtual method is invoked if the client fails the static security checks. The

failure may be overridden or deferred. Asynchronous operations are possible.

3) CSession2::ServiceL

The static policy checks could be deferred until the session is created provided that

the server connection API is not guarded by user prompts.

*** Example integration ***

In the example code a combination of (2) and (3) are used because it involves

minimal changes to the existing security policy checks.

**** Steps **** 

1) An RUpsSession object has been added to the CMsgServer class. This is

initialized at startup.

2) CMsgServer::iPolicyElements was changed to cause CustomFailureActionL to be

invoked if the static security policy check fails instead of failing the

client.

3) CMsgServer::CustomFailureActionL notifies the session object that the

platsec check failed. This is important because RUpsSubsession::Authorise

requires this information in order to allow unconfigured systems to be

compatible with platsec. It also increases the flexibility of the UPS policy

definitions.

4) An RUpsSubsession instance is created for each CSession2 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.

5) An extra state (iAuthorising) was added at the start of the CMsgProcessor

   state machine.

6) The RMessage2 parameters from the client API are now extracted in the

authorization stage to enable the information to be passed to the UPS.

7) CMsgProcessor::DoCancel was updated to cancel the call to

RUpsSubsession::Authorise if the client cancels the sending of the message or

disconnects.

8) CMsgProcessor::RunL now checks whether the request was authorized before

changing from the authorization to the sending state.