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.
sl@0
     1
//
sl@0
     2
// Copyright (c) Symbian Software Ltd 2007. All rights reserved.
sl@0
     3
//
sl@0
     4
sl@0
     5
sl@0
     6
*** Overview ***
sl@0
     7
sl@0
     8
This directory contains example code that demonstrates how user permission
sl@0
     9
prompt support(UPS) may be added to a system server. The example code consists of
sl@0
    10
three components.
sl@0
    11
sl@0
    12
*** Components ***
sl@0
    13
sl@0
    14
1) tmsgserver 
sl@0
    15
A simple server that provides an asynchronous API to send messages. Since this
sl@0
    16
is example code the messages are displayed to the screen.
sl@0
    17
sl@0
    18
2) tmsclient 
sl@0
    19
The client library for tmsgserver.  
sl@0
    20
No modifications are necessary in order to support user permission prompts.
sl@0
    21
sl@0
    22
3) tmsgapp
sl@0
    23
An example application that sends a number of messages and also tests cancellation. 
sl@0
    24
sl@0
    25
No modification was required as a consequence of the UPS integration. However,
sl@0
    26
in order to allow the test to be run multiple times the UPS management API is
sl@0
    27
used to delete old decision records for this application.
sl@0
    28
sl@0
    29
*** Integration Overview *** 
sl@0
    30
Whilst the APIs for the UPS are relatively small the integration is slightly
sl@0
    31
more complicated than might be expected because existing synchronous security
sl@0
    32
checks must become asynchronous since interaction with the device user is
sl@0
    33
inherently an asynchronous operation. For example, it would be undesirable to
sl@0
    34
block the entire network server whilst waiting for the user to respond to a
sl@0
    35
dialog.
sl@0
    36
sl@0
    37
The second factor that must be considered is that in order to make an informed
sl@0
    38
security decision the user may need to know data about the request they are
sl@0
    39
authorizing. Consequently, it may be necessary to extract the parameters from
sl@0
    40
the client application at the security check stage.
sl@0
    41
sl@0
    42
Finally, depending on the service and the security requirements of the
sl@0
    43
manufacturer an operator user prompts may be in addition to the platform
sl@0
    44
security (e.g. capabilities) checks. Alternatively, user prompts could be used
sl@0
    45
to allow applications without capabilities limited access to a protected
sl@0
    46
service. Since most implementations of the CPolicyServer fail the client
sl@0
    47
immediately if the platsec check fails these checks may have to be modified.
sl@0
    48
sl@0
    49
*** Integration Points *** 
sl@0
    50
If the system server uses the CPolicyServer framework then there are three
sl@0
    51
candidates for the main integration point.
sl@0
    52
sl@0
    53
1) CPolicyServer::CustomSecurityCheckL
sl@0
    54
This allows an arbitrary and even asynchronous check to be made instead of using
sl@0
    55
static security policies.
sl@0
    56
sl@0
    57
2) CPolicyServer::CustomFailureActionL
sl@0
    58
This virtual method is invoked if the client fails the static security checks. The
sl@0
    59
failure may be overridden or deferred. Asynchronous operations are possible.
sl@0
    60
sl@0
    61
3) CSession2::ServiceL
sl@0
    62
The static policy checks could be deferred until the session is created provided that
sl@0
    63
the server connection API is not guarded by user prompts.
sl@0
    64
sl@0
    65
*** Example integration ***
sl@0
    66
In the example code a combination of (2) and (3) are used because it involves
sl@0
    67
minimal changes to the existing security policy checks.
sl@0
    68
sl@0
    69
**** Steps **** 
sl@0
    70
sl@0
    71
1) An RUpsSession object has been added to the CMsgServer class. This is
sl@0
    72
initialized at startup.
sl@0
    73
sl@0
    74
2) CMsgServer::iPolicyElements was changed to cause CustomFailureActionL to be
sl@0
    75
invoked if the static security policy check fails instead of failing the
sl@0
    76
client.
sl@0
    77
sl@0
    78
3) CMsgServer::CustomFailureActionL notifies the session object that the
sl@0
    79
platsec check failed. This is important because RUpsSubsession::Authorise
sl@0
    80
requires this information in order to allow unconfigured systems to be
sl@0
    81
compatible with platsec. It also increases the flexibility of the UPS policy
sl@0
    82
definitions.
sl@0
    83
sl@0
    84
4) An RUpsSubsession instance is created for each CSession2 object. i.e.
sl@0
    85
requests from different clients are authorized independently. This could be
sl@0
    86
modified so that there is one UPS sub-session for each client process instead
sl@0
    87
of each connection from a client process.
sl@0
    88
sl@0
    89
5) An extra state (iAuthorising) was added at the start of the CMsgProcessor
sl@0
    90
   state machine.
sl@0
    91
sl@0
    92
6) The RMessage2 parameters from the client API are now extracted in the
sl@0
    93
authorization stage to enable the information to be passed to the UPS.
sl@0
    94
sl@0
    95
7) CMsgProcessor::DoCancel was updated to cancel the call to
sl@0
    96
RUpsSubsession::Authorise if the client cancels the sending of the message or
sl@0
    97
disconnects.
sl@0
    98
sl@0
    99
8) CMsgProcessor::RunL now checks whether the request was authorized before
sl@0
   100
changing from the authorization to the sending state.
sl@0
   101
sl@0
   102
sl@0
   103
sl@0
   104