1 //

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

     3 //

     4 

     5 

     6 *** Overview ***

     7 

     8 This directory contains example code that demonstrates how user permission

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

    10 three components.

    11 

    12 *** Components ***

    13 

    14 1) tmsgserver 

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

    16 is example code the messages are displayed to the screen.

    17 

    18 2) tmsclient 

    19 The client library for tmsgserver.  

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

    21 

    22 3) tmsgapp

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

    24 

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

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

    27 used to delete old decision records for this application.

    28 

    29 *** Integration Overview *** 

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

    31 more complicated than might be expected because existing synchronous security

    32 checks must become asynchronous since interaction with the device user is

    33 inherently an asynchronous operation. For example, it would be undesirable to

    34 block the entire network server whilst waiting for the user to respond to a

    35 dialog.

    36 

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

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

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

    40 the client application at the security check stage.

    41 

    42 Finally, depending on the service and the security requirements of the

    43 manufacturer an operator user prompts may be in addition to the platform

    44 security (e.g. capabilities) checks. Alternatively, user prompts could be used

    45 to allow applications without capabilities limited access to a protected

    46 service. Since most implementations of the CPolicyServer fail the client

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

    48 

    49 *** Integration Points *** 

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

    51 candidates for the main integration point.

    52 

    53 1) CPolicyServer::CustomSecurityCheckL

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

    55 static security policies.

    56 

    57 2) CPolicyServer::CustomFailureActionL

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

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

    60 

    61 3) CSession2::ServiceL

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

    63 the server connection API is not guarded by user prompts.

    64 

    65 *** Example integration ***

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

    67 minimal changes to the existing security policy checks.

    68 

    69 **** Steps **** 

    70 

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

    72 initialized at startup.

    73 

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

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

    76 client.

    77 

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

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

    80 requires this information in order to allow unconfigured systems to be

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

    82 definitions.

    83 

    84 4) An RUpsSubsession instance is created for each CSession2 object. i.e.

    85 requests from different clients are authorized independently. This could be

    86 modified so that there is one UPS sub-session for each client process instead

    87 of each connection from a client process.

    88 

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

    90    state machine.

    91 

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

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

    94 

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

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

    97 disconnects.

    98 

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

   100 changing from the authorization to the sending state.

   101 

   102 

   103 

   104