/*
* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: 
* Resource header for User Prompt Service Policy files.
*
*/


/**
 @file policies.rh
 @publishedPartner
 @released
*/

#ifndef POLICIES_RH
#define POLICIES_RH

#include <ups/ups.hrh>

/** 
This resource header file defines the structures and constants required by User
Prompt Service policy files.

A policy file is specific to an single service provided by a specific system
server and determines whether clients requesting that service from the system
server should be silently accepted/denied or require the user to be prompted.

A policy file consists of an arbitrary number of policies. The User Prompt
Service searches through the file in order attempting to match.

* The secure id of the client application.
* The destination field  (e.g. a phone number) provided by the system server. 
* If the policy only applies if the security check implemented by the system
  server passed/failed.

The first matching policy is the policy that is used so policies must be 
ordered from most specific to least specific.

The policies for a given service are defined by a single policy file and must
be named as follows ups_SystemServerSid_ServiceUid.rsc

Where the UID or SID is an 8 digit hexadecimal number.

A policy file has the following structure

UID2 KUidUpsPolicyResourceFile  // Identifies this as a UPS policy file
UID3 0xXXXXXXXX                 // Uniquely defines this policy file.
                                // The UID should be reserved using the
                                // Symbian Signed protected UID allocator.

RESOURCE POLICIES mypolicies
    {
    header = POLICY_HEADER 
        {
        // header definition
        };
policies = 
    {
    POLICY
        {
        // definition of policy 1
        },
    POLICY
        {
        // definition of policy 2
        }
    // etc
    };
}
*/

/**
Defines whether a dialog should be displayed and if so, the
set of options that should be presented in the dialog.

If just KYes or just KNo is defined then a prompt won't be displayed
and the request will be silently accepted/denied.
*/

#define KYes        0x0001
#define KNo         0x0002
#define KSession    0x0004 // Implicitly "yes", name kept for compatibility
#define KSessionYes 0x0004 // New name, same value/meaning as old Session option
#define KAlways     0x0008
#define KNever      0x0010
#define KSessionNo  0x0020

/** Secure ID (SID) classes defined by Symbian Signed.  

SID classes partition the UID range into 16 classes based on the most
significant nybble of the UID number.  
E.g. V9 protected UID allocates are always allocated from Class 2

Typically, policies would be based on the protected range (classes 0 - 7)
or the unprotected range (classes 8 - F). This is Software Install only
allows the installation of executables with protected SIDs if the package
is signed. Consequently, the identity of an application may only accurately
be verified via the SIS registry if the application has a protected SID.

See also - Symbian Signed UID FAQ
*/
#define KSidClass0  0x00000001
#define KSidClass1  0x00000002
#define KSidClass2  0x00000004
#define KSidClass3  0x00000008
#define KSidClass4  0x00000010
#define KSidClass5  0x00000020
#define KSidClass6  0x00000040
#define KSidClass7  0x00000080
#define KSidClass8  0x00000100
#define KSidClass9  0x00000200
#define KSidClassA  0x00000400
#define KSidClassB  0x00000800
#define KSidClassC  0x00001000
#define KSidClassD  0x00002000
#define KSidClassE  0x00004000
#define KSidClassF  0x00008000

// Commonly used SID class definitions
#define KProtectedSids      KSidClass0|KSidClass1|KSidClass2|KSidClass3|KSidClass4|KSidClass5|KSidClass6|KSidClass7
#define KUnprotectedSids    KSidClass8|KSidClass9|KSidClassA|KSidClassB|KSidClassC|KSidClassD|KSidClassE|KSidClassF
#define KAllSids            0x0000FFFF


/**
Specifies whether authorisation from the User Prompt Service is required for 
requests from clients that passed the system server's security check.

Note that protected SID checks are based on the SID of the application excutable
issuing the request, not the UID of the package owning that executable.

If a policy file is not defined for a system server or service then a default
value of ECheckNever will be used because this is compatible with the existing
platform security behavior.
*/
ENUM TAuthorisationPolicy
  {		
	/**
	Ignore the system server (platsec) checks, and always ask the UPS what to do.
	*/
	EAlwaysCheck = 0,	
	
	/**
	For application executables with a protected SID,  launched from the
	Z drive, where the system server checks have passed, allow the request.
	Otherwise call the UPS which may still choose to  allow the request.
	
	For all other executables, ignore the system server (platsec) checks, and 
	always ask the UPS what to do.
	*/		 
	ECheckPostManufacture = 1,
	
	/** 
	For application executables with a protected SID (regardless of drive), where
	the system server checks have passed, allow the request.
	Otherwise call the UPS which may still choose to  allow the request.
	
	For all other executables, ignore the system server (platsec) checks, and 
	always ask the UPS what to do.
	*/
	ECheckUnprotectedSids = 2,
	
	/** 
	If the system server checks passed, allow the request.
	If they failed, call the UPS which may still choose to  allow the request.
	*/
	ECheckIfFailed = 3,
	
	/** 
	If the system server checks passed, allow the request.
	If the system server checks failed, reject the request.
		
	Never query the UPS - just use existing security check result implemented
	by system server.
	*/
	ENeverCheck = 4
    }

STRUCT POLICY_HEADER
    {
	// The major version number of THIS policy file.
	// When policy files are upgraded or eclipsed the UPS deletes all decision
	// records for the system server server SID and service ID where the major
	// version in the decision record is not equal to the major version 
	// number in the policy file.
	WORD majorversion = 0;

	// The minor version number of THIS policy file.
	WORD minorversion = 0;

	// Determines whether a system server must request authorisation from the
	// User Prompt Service even if the client application passed the system
	// server's security check.
    BYTE authorisationpolicy = ECheckPostManufacture;
    
    // Defines the implementation UID of the default policy evaluator.
    // This MUST be defined and non-zero.
    LONG  policyevaluator = 0;

    // Defines the implementation UID of the default dialog creator.
    // This MUST be defined and non-zero.
    LONG  dialogcreator = 0;    
    }

/**
Allows policies to be matched according to whether the client process
passed security check defined by the system server.
Typically, this corresponds to whether the client has the correct capabilities
for the requested service. However, system servers are free to use features
other than capabilities in their security check.

E.g. If the client has the correct capabilities for the requested service then
the "Always" and "Never" options will be enabled in the policy; otherwise, a
different policy will be matched where the prompt is limited to one-shot
permissions ("Yes" and "No").

*/
ENUM TSystemServerSecurity
   { 
   /**
   The policy applies regardless of whether the client process passed the
   system server's security check.
   */
   ESystemServerSecurityPassedOrFailed = 0,
   /**
   The policy only applies if the client process failed the system server's
   security check.
   */
   ESystemServerSecurityFailed = 1,
   /**
   The policy only applies if the client process passed the system server's
   security check.
   */
   ESystemServerSecurityPassed = 2
   }

// Defines a single policy
STRUCT POLICY
    {
    // A bitmask that defines the set of SID classes that this policy applies to.
    // Typically, this field is used if a policy applies 
	// All clients with a protected SID		- KProtectedSids
    // All clients with an unprotected SID	- KUnprotectedSids
	// All clients							- KAllSids
    LONG    sid_classes = KAllSids;

    // An array of LONGs that defines a set of specific client application SIDs 
	// that this policy applies to.
    // If this field is populated then the sid_classes field will be ignored.
    LONG    sid_list[];

	// By default policies apply regardless of whether the client process
	// requesting the service passed or failed the system server's security
	// check. i.e. whether the client process has the correct capabilities.
    BYTE    systemserversecurity = ESystemServerSecurityPassedOrFailed;

    // A wildcard string to match against destination supplied by system server
	// Wildcard rules are defined by TDesC::MatchF
    LTEXT   destination = "*";

    // A bit field that controls which buttons may be displayed.
    // KYes, KNo, KSessionYes, KSessionNo, KAlways, KNever
    LONG    options = KYes|KNo;

    // If non-zero, this field overrides the implementation UID
    // of the default policy evaluator for this policy.
    LONG    policyevaluator = 0;

    // If non-zero, this field overrides the implementation UID
    // of the default dialog creator.
    LONG    dialogcreator = 0;

    // Flags specific to the policy evaluator
    WORD    flags = 0;

    // Reserved for future use, do not use
    WORD    reservedWord = 0;

    // Reserved for future use, do not use
    LLINK   reservedLink = 0;
    }

// Defines a set of policies and the implementations UIDs of the default
// policy evaluator and dialog creator plug-ins.
STRUCT POLICIES
    {
    // Version of the UPS policy format.
	// Policy files MUST NOT change this value.
    WORD version = 1;

    // reserved for future use, do not use
    LLINK reserved = 0;

    // A POLICY_HEADER structure
    STRUCT header;

    // An array of POLICY structures
    STRUCT policies[];
    }

#endif