2 // Copyright (c) Symbian Software Ltd 2007. All rights reserved.
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
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.
19 The client library for tmsgserver.
20 No modifications are necessary in order to support user permission prompts.
23 An example application that sends a number of messages and also tests cancellation.
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.
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
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.
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.
49 *** Integration Points ***
50 If the system server uses the CPolicyServer framework then there are three
51 candidates for the main integration point.
53 1) CPolicyServer::CustomSecurityCheckL
54 This allows an arbitrary and even asynchronous check to be made instead of using
55 static security policies.
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.
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.
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.
71 1) An RUpsSession object has been added to the CMsgServer class. This is
72 initialized at startup.
74 2) CMsgServer::iPolicyElements was changed to cause CustomFailureActionL to be
75 invoked if the static security policy check fails instead of failing the
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
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.
89 5) An extra state (iAuthorising) was added at the start of the CMsgProcessor
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.
95 7) CMsgProcessor::DoCancel was updated to cancel the call to
96 RUpsSubsession::Authorise if the client cancels the sending of the message or
99 8) CMsgProcessor::RunL now checks whether the request was authorized before
100 changing from the authorization to the sending state.