os/security/authorisation/userpromptservice/examples/integration/readme.txt
author sl
Tue, 10 Jun 2014 14:32:02 +0200
changeset 1 260cb5ec6c19
permissions -rw-r--r--
Update contrib.
     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