1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/os/security/authorisation/userpromptservice/examples/integration/readme.txt	Fri Jun 15 03:10:57 2012 +0200
     1.3 @@ -0,0 +1,104 @@
     1.4 +//
     1.5 +// Copyright (c) Symbian Software Ltd 2007. All rights reserved.
     1.6 +//
     1.7 +
     1.8 +
     1.9 +*** Overview ***
    1.10 +
    1.11 +This directory contains example code that demonstrates how user permission
    1.12 +prompt support(UPS) may be added to a system server. The example code consists of
    1.13 +three components.
    1.14 +
    1.15 +*** Components ***
    1.16 +
    1.17 +1) tmsgserver 
    1.18 +A simple server that provides an asynchronous API to send messages. Since this
    1.19 +is example code the messages are displayed to the screen.
    1.20 +
    1.21 +2) tmsclient 
    1.22 +The client library for tmsgserver.  
    1.23 +No modifications are necessary in order to support user permission prompts.
    1.24 +
    1.25 +3) tmsgapp
    1.26 +An example application that sends a number of messages and also tests cancellation. 
    1.27 +
    1.28 +No modification was required as a consequence of the UPS integration. However,
    1.29 +in order to allow the test to be run multiple times the UPS management API is
    1.30 +used to delete old decision records for this application.
    1.31 +
    1.32 +*** Integration Overview *** 
    1.33 +Whilst the APIs for the UPS are relatively small the integration is slightly
    1.34 +more complicated than might be expected because existing synchronous security
    1.35 +checks must become asynchronous since interaction with the device user is
    1.36 +inherently an asynchronous operation. For example, it would be undesirable to
    1.37 +block the entire network server whilst waiting for the user to respond to a
    1.38 +dialog.
    1.39 +
    1.40 +The second factor that must be considered is that in order to make an informed
    1.41 +security decision the user may need to know data about the request they are
    1.42 +authorizing. Consequently, it may be necessary to extract the parameters from
    1.43 +the client application at the security check stage.
    1.44 +
    1.45 +Finally, depending on the service and the security requirements of the
    1.46 +manufacturer an operator user prompts may be in addition to the platform
    1.47 +security (e.g. capabilities) checks. Alternatively, user prompts could be used
    1.48 +to allow applications without capabilities limited access to a protected
    1.49 +service. Since most implementations of the CPolicyServer fail the client
    1.50 +immediately if the platsec check fails these checks may have to be modified.
    1.51 +
    1.52 +*** Integration Points *** 
    1.53 +If the system server uses the CPolicyServer framework then there are three
    1.54 +candidates for the main integration point.
    1.55 +
    1.56 +1) CPolicyServer::CustomSecurityCheckL
    1.57 +This allows an arbitrary and even asynchronous check to be made instead of using
    1.58 +static security policies.
    1.59 +
    1.60 +2) CPolicyServer::CustomFailureActionL
    1.61 +This virtual method is invoked if the client fails the static security checks. The
    1.62 +failure may be overridden or deferred. Asynchronous operations are possible.
    1.63 +
    1.64 +3) CSession2::ServiceL
    1.65 +The static policy checks could be deferred until the session is created provided that
    1.66 +the server connection API is not guarded by user prompts.
    1.67 +
    1.68 +*** Example integration ***
    1.69 +In the example code a combination of (2) and (3) are used because it involves
    1.70 +minimal changes to the existing security policy checks.
    1.71 +
    1.72 +**** Steps **** 
    1.73 +
    1.74 +1) An RUpsSession object has been added to the CMsgServer class. This is
    1.75 +initialized at startup.
    1.76 +
    1.77 +2) CMsgServer::iPolicyElements was changed to cause CustomFailureActionL to be
    1.78 +invoked if the static security policy check fails instead of failing the
    1.79 +client.
    1.80 +
    1.81 +3) CMsgServer::CustomFailureActionL notifies the session object that the
    1.82 +platsec check failed. This is important because RUpsSubsession::Authorise
    1.83 +requires this information in order to allow unconfigured systems to be
    1.84 +compatible with platsec. It also increases the flexibility of the UPS policy
    1.85 +definitions.
    1.86 +
    1.87 +4) An RUpsSubsession instance is created for each CSession2 object. i.e.
    1.88 +requests from different clients are authorized independently. This could be
    1.89 +modified so that there is one UPS sub-session for each client process instead
    1.90 +of each connection from a client process.
    1.91 +
    1.92 +5) An extra state (iAuthorising) was added at the start of the CMsgProcessor
    1.93 +   state machine.
    1.94 +
    1.95 +6) The RMessage2 parameters from the client API are now extracted in the
    1.96 +authorization stage to enable the information to be passed to the UPS.
    1.97 +
    1.98 +7) CMsgProcessor::DoCancel was updated to cancel the call to
    1.99 +RUpsSubsession::Authorise if the client cancels the sending of the message or
   1.100 +disconnects.
   1.101 +
   1.102 +8) CMsgProcessor::RunL now checks whether the request was authorized before
   1.103 +changing from the authorization to the sending state.
   1.104 +
   1.105 +
   1.106 +
   1.107 +