sl@0: // sl@0: // Copyright (c) Symbian Software Ltd 2007. All rights reserved. sl@0: // sl@0: sl@0: sl@0: *** Overview *** sl@0: sl@0: This directory contains example code that demonstrates how user permission sl@0: prompt support(UPS) may be added to a system server. The example code consists of sl@0: three components. sl@0: sl@0: *** Components *** sl@0: sl@0: 1) tmsgserver sl@0: A simple server that provides an asynchronous API to send messages. Since this sl@0: is example code the messages are displayed to the screen. sl@0: sl@0: 2) tmsclient sl@0: The client library for tmsgserver. sl@0: No modifications are necessary in order to support user permission prompts. sl@0: sl@0: 3) tmsgapp sl@0: An example application that sends a number of messages and also tests cancellation. sl@0: sl@0: No modification was required as a consequence of the UPS integration. However, sl@0: in order to allow the test to be run multiple times the UPS management API is sl@0: used to delete old decision records for this application. sl@0: sl@0: *** Integration Overview *** sl@0: Whilst the APIs for the UPS are relatively small the integration is slightly sl@0: more complicated than might be expected because existing synchronous security sl@0: checks must become asynchronous since interaction with the device user is sl@0: inherently an asynchronous operation. For example, it would be undesirable to sl@0: block the entire network server whilst waiting for the user to respond to a sl@0: dialog. sl@0: sl@0: The second factor that must be considered is that in order to make an informed sl@0: security decision the user may need to know data about the request they are sl@0: authorizing. Consequently, it may be necessary to extract the parameters from sl@0: the client application at the security check stage. sl@0: sl@0: Finally, depending on the service and the security requirements of the sl@0: manufacturer an operator user prompts may be in addition to the platform sl@0: security (e.g. capabilities) checks. Alternatively, user prompts could be used sl@0: to allow applications without capabilities limited access to a protected sl@0: service. Since most implementations of the CPolicyServer fail the client sl@0: immediately if the platsec check fails these checks may have to be modified. sl@0: sl@0: *** Integration Points *** sl@0: If the system server uses the CPolicyServer framework then there are three sl@0: candidates for the main integration point. sl@0: sl@0: 1) CPolicyServer::CustomSecurityCheckL sl@0: This allows an arbitrary and even asynchronous check to be made instead of using sl@0: static security policies. sl@0: sl@0: 2) CPolicyServer::CustomFailureActionL sl@0: This virtual method is invoked if the client fails the static security checks. The sl@0: failure may be overridden or deferred. Asynchronous operations are possible. sl@0: sl@0: 3) CSession2::ServiceL sl@0: The static policy checks could be deferred until the session is created provided that sl@0: the server connection API is not guarded by user prompts. sl@0: sl@0: *** Example integration *** sl@0: In the example code a combination of (2) and (3) are used because it involves sl@0: minimal changes to the existing security policy checks. sl@0: sl@0: **** Steps **** sl@0: sl@0: 1) An RUpsSession object has been added to the CMsgServer class. This is sl@0: initialized at startup. sl@0: sl@0: 2) CMsgServer::iPolicyElements was changed to cause CustomFailureActionL to be sl@0: invoked if the static security policy check fails instead of failing the sl@0: client. sl@0: sl@0: 3) CMsgServer::CustomFailureActionL notifies the session object that the sl@0: platsec check failed. This is important because RUpsSubsession::Authorise sl@0: requires this information in order to allow unconfigured systems to be sl@0: compatible with platsec. It also increases the flexibility of the UPS policy sl@0: definitions. sl@0: sl@0: 4) An RUpsSubsession instance is created for each CSession2 object. i.e. sl@0: requests from different clients are authorized independently. This could be sl@0: modified so that there is one UPS sub-session for each client process instead sl@0: of each connection from a client process. sl@0: sl@0: 5) An extra state (iAuthorising) was added at the start of the CMsgProcessor sl@0: state machine. sl@0: sl@0: 6) The RMessage2 parameters from the client API are now extracted in the sl@0: authorization stage to enable the information to be passed to the UPS. sl@0: sl@0: 7) CMsgProcessor::DoCancel was updated to cancel the call to sl@0: RUpsSubsession::Authorise if the client cancels the sending of the message or sl@0: disconnects. sl@0: sl@0: 8) CMsgProcessor::RunL now checks whether the request was authorized before sl@0: changing from the authorization to the sending state. sl@0: sl@0: sl@0: sl@0: