--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/authorisation/userpromptservice/examples/integration/readme.txt	Thu Sep 10 14:01:51 2009 +0300
@@ -0,0 +1,104 @@
+//
+// 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.
+
+
+
+