sl@0: /*
sl@0: * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: * All rights reserved.
sl@0: * This component and the accompanying materials are made available
sl@0: * under the terms of the License "Eclipse Public License v1.0"
sl@0: * which accompanies this distribution, and is available
sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: *
sl@0: * Initial Contributors:
sl@0: * Nokia Corporation - initial contribution.
sl@0: *
sl@0: * Contributors:
sl@0: *
sl@0: * Description: 
sl@0: * Resource header for User Prompt Service Policy files.
sl@0: *
sl@0: */
sl@0: 
sl@0: 
sl@0: /**
sl@0:  @file policies.rh
sl@0:  @publishedPartner
sl@0:  @released
sl@0: */
sl@0: 
sl@0: #ifndef POLICIES_RH
sl@0: #define POLICIES_RH
sl@0: 
sl@0: #include <ups/ups.hrh>
sl@0: 
sl@0: /** 
sl@0: This resource header file defines the structures and constants required by User
sl@0: Prompt Service policy files.
sl@0: 
sl@0: A policy file is specific to an single service provided by a specific system
sl@0: server and determines whether clients requesting that service from the system
sl@0: server should be silently accepted/denied or require the user to be prompted.
sl@0: 
sl@0: A policy file consists of an arbitrary number of policies. The User Prompt
sl@0: Service searches through the file in order attempting to match.
sl@0: 
sl@0: * The secure id of the client application.
sl@0: * The destination field  (e.g. a phone number) provided by the system server. 
sl@0: * If the policy only applies if the security check implemented by the system
sl@0:   server passed/failed.
sl@0: 
sl@0: The first matching policy is the policy that is used so policies must be 
sl@0: ordered from most specific to least specific.
sl@0: 
sl@0: The policies for a given service are defined by a single policy file and must
sl@0: be named as follows ups_SystemServerSid_ServiceUid.rsc
sl@0: 
sl@0: Where the UID or SID is an 8 digit hexadecimal number.
sl@0: 
sl@0: A policy file has the following structure
sl@0: 
sl@0: UID2 KUidUpsPolicyResourceFile  // Identifies this as a UPS policy file
sl@0: UID3 0xXXXXXXXX                 // Uniquely defines this policy file.
sl@0:                                 // The UID should be reserved using the
sl@0:                                 // Symbian Signed protected UID allocator.
sl@0: 
sl@0: RESOURCE POLICIES mypolicies
sl@0:     {
sl@0:     header = POLICY_HEADER 
sl@0:         {
sl@0:         // header definition
sl@0:         };
sl@0: policies = 
sl@0:     {
sl@0:     POLICY
sl@0:         {
sl@0:         // definition of policy 1
sl@0:         },
sl@0:     POLICY
sl@0:         {
sl@0:         // definition of policy 2
sl@0:         }
sl@0:     // etc
sl@0:     };
sl@0: }
sl@0: */
sl@0: 
sl@0: /**
sl@0: Defines whether a dialog should be displayed and if so, the
sl@0: set of options that should be presented in the dialog.
sl@0: 
sl@0: If just KYes or just KNo is defined then a prompt won't be displayed
sl@0: and the request will be silently accepted/denied.
sl@0: */
sl@0: 
sl@0: #define KYes        0x0001
sl@0: #define KNo         0x0002
sl@0: #define KSession    0x0004 // Implicitly "yes", name kept for compatibility
sl@0: #define KSessionYes 0x0004 // New name, same value/meaning as old Session option
sl@0: #define KAlways     0x0008
sl@0: #define KNever      0x0010
sl@0: #define KSessionNo  0x0020
sl@0: 
sl@0: /** Secure ID (SID) classes defined by Symbian Signed.  
sl@0: 
sl@0: SID classes partition the UID range into 16 classes based on the most
sl@0: significant nybble of the UID number.  
sl@0: E.g. V9 protected UID allocates are always allocated from Class 2
sl@0: 
sl@0: Typically, policies would be based on the protected range (classes 0 - 7)
sl@0: or the unprotected range (classes 8 - F). This is Software Install only
sl@0: allows the installation of executables with protected SIDs if the package
sl@0: is signed. Consequently, the identity of an application may only accurately
sl@0: be verified via the SIS registry if the application has a protected SID.
sl@0: 
sl@0: See also - Symbian Signed UID FAQ
sl@0: */
sl@0: #define KSidClass0  0x00000001
sl@0: #define KSidClass1  0x00000002
sl@0: #define KSidClass2  0x00000004
sl@0: #define KSidClass3  0x00000008
sl@0: #define KSidClass4  0x00000010
sl@0: #define KSidClass5  0x00000020
sl@0: #define KSidClass6  0x00000040
sl@0: #define KSidClass7  0x00000080
sl@0: #define KSidClass8  0x00000100
sl@0: #define KSidClass9  0x00000200
sl@0: #define KSidClassA  0x00000400
sl@0: #define KSidClassB  0x00000800
sl@0: #define KSidClassC  0x00001000
sl@0: #define KSidClassD  0x00002000
sl@0: #define KSidClassE  0x00004000
sl@0: #define KSidClassF  0x00008000
sl@0: 
sl@0: // Commonly used SID class definitions
sl@0: #define KProtectedSids      KSidClass0|KSidClass1|KSidClass2|KSidClass3|KSidClass4|KSidClass5|KSidClass6|KSidClass7
sl@0: #define KUnprotectedSids    KSidClass8|KSidClass9|KSidClassA|KSidClassB|KSidClassC|KSidClassD|KSidClassE|KSidClassF
sl@0: #define KAllSids            0x0000FFFF
sl@0: 
sl@0: 
sl@0: /**
sl@0: Specifies whether authorisation from the User Prompt Service is required for 
sl@0: requests from clients that passed the system server's security check.
sl@0: 
sl@0: Note that protected SID checks are based on the SID of the application excutable
sl@0: issuing the request, not the UID of the package owning that executable.
sl@0: 
sl@0: If a policy file is not defined for a system server or service then a default
sl@0: value of ECheckNever will be used because this is compatible with the existing
sl@0: platform security behavior.
sl@0: */
sl@0: ENUM TAuthorisationPolicy
sl@0:   {		
sl@0: 	/**
sl@0: 	Ignore the system server (platsec) checks, and always ask the UPS what to do.
sl@0: 	*/
sl@0: 	EAlwaysCheck = 0,	
sl@0: 	
sl@0: 	/**
sl@0: 	For application executables with a protected SID,  launched from the
sl@0: 	Z drive, where the system server checks have passed, allow the request.
sl@0: 	Otherwise call the UPS which may still choose to  allow the request.
sl@0: 	
sl@0: 	For all other executables, ignore the system server (platsec) checks, and 
sl@0: 	always ask the UPS what to do.
sl@0: 	*/		 
sl@0: 	ECheckPostManufacture = 1,
sl@0: 	
sl@0: 	/** 
sl@0: 	For application executables with a protected SID (regardless of drive), where
sl@0: 	the system server checks have passed, allow the request.
sl@0: 	Otherwise call the UPS which may still choose to  allow the request.
sl@0: 	
sl@0: 	For all other executables, ignore the system server (platsec) checks, and 
sl@0: 	always ask the UPS what to do.
sl@0: 	*/
sl@0: 	ECheckUnprotectedSids = 2,
sl@0: 	
sl@0: 	/** 
sl@0: 	If the system server checks passed, allow the request.
sl@0: 	If they failed, call the UPS which may still choose to  allow the request.
sl@0: 	*/
sl@0: 	ECheckIfFailed = 3,
sl@0: 	
sl@0: 	/** 
sl@0: 	If the system server checks passed, allow the request.
sl@0: 	If the system server checks failed, reject the request.
sl@0: 		
sl@0: 	Never query the UPS - just use existing security check result implemented
sl@0: 	by system server.
sl@0: 	*/
sl@0: 	ENeverCheck = 4
sl@0:     }
sl@0: 
sl@0: STRUCT POLICY_HEADER
sl@0:     {
sl@0: 	// The major version number of THIS policy file.
sl@0: 	// When policy files are upgraded or eclipsed the UPS deletes all decision
sl@0: 	// records for the system server server SID and service ID where the major
sl@0: 	// version in the decision record is not equal to the major version 
sl@0: 	// number in the policy file.
sl@0: 	WORD majorversion = 0;
sl@0: 
sl@0: 	// The minor version number of THIS policy file.
sl@0: 	WORD minorversion = 0;
sl@0: 
sl@0: 	// Determines whether a system server must request authorisation from the
sl@0: 	// User Prompt Service even if the client application passed the system
sl@0: 	// server's security check.
sl@0:     BYTE authorisationpolicy = ECheckPostManufacture;
sl@0:     
sl@0:     // Defines the implementation UID of the default policy evaluator.
sl@0:     // This MUST be defined and non-zero.
sl@0:     LONG  policyevaluator = 0;
sl@0: 
sl@0:     // Defines the implementation UID of the default dialog creator.
sl@0:     // This MUST be defined and non-zero.
sl@0:     LONG  dialogcreator = 0;    
sl@0:     }
sl@0: 
sl@0: /**
sl@0: Allows policies to be matched according to whether the client process
sl@0: passed security check defined by the system server.
sl@0: Typically, this corresponds to whether the client has the correct capabilities
sl@0: for the requested service. However, system servers are free to use features
sl@0: other than capabilities in their security check.
sl@0: 
sl@0: E.g. If the client has the correct capabilities for the requested service then
sl@0: the "Always" and "Never" options will be enabled in the policy; otherwise, a
sl@0: different policy will be matched where the prompt is limited to one-shot
sl@0: permissions ("Yes" and "No").
sl@0: 
sl@0: */
sl@0: ENUM TSystemServerSecurity
sl@0:    { 
sl@0:    /**
sl@0:    The policy applies regardless of whether the client process passed the
sl@0:    system server's security check.
sl@0:    */
sl@0:    ESystemServerSecurityPassedOrFailed = 0,
sl@0:    /**
sl@0:    The policy only applies if the client process failed the system server's
sl@0:    security check.
sl@0:    */
sl@0:    ESystemServerSecurityFailed = 1,
sl@0:    /**
sl@0:    The policy only applies if the client process passed the system server's
sl@0:    security check.
sl@0:    */
sl@0:    ESystemServerSecurityPassed = 2
sl@0:    }
sl@0: 
sl@0: // Defines a single policy
sl@0: STRUCT POLICY
sl@0:     {
sl@0:     // A bitmask that defines the set of SID classes that this policy applies to.
sl@0:     // Typically, this field is used if a policy applies 
sl@0: 	// All clients with a protected SID		- KProtectedSids
sl@0:     // All clients with an unprotected SID	- KUnprotectedSids
sl@0: 	// All clients							- KAllSids
sl@0:     LONG    sid_classes = KAllSids;
sl@0: 
sl@0:     // An array of LONGs that defines a set of specific client application SIDs 
sl@0: 	// that this policy applies to.
sl@0:     // If this field is populated then the sid_classes field will be ignored.
sl@0:     LONG    sid_list[];
sl@0: 
sl@0: 	// By default policies apply regardless of whether the client process
sl@0: 	// requesting the service passed or failed the system server's security
sl@0: 	// check. i.e. whether the client process has the correct capabilities.
sl@0:     BYTE    systemserversecurity = ESystemServerSecurityPassedOrFailed;
sl@0: 
sl@0:     // A wildcard string to match against destination supplied by system server
sl@0: 	// Wildcard rules are defined by TDesC::MatchF
sl@0:     LTEXT   destination = "*";
sl@0: 
sl@0:     // A bit field that controls which buttons may be displayed.
sl@0:     // KYes, KNo, KSessionYes, KSessionNo, KAlways, KNever
sl@0:     LONG    options = KYes|KNo;
sl@0: 
sl@0:     // If non-zero, this field overrides the implementation UID
sl@0:     // of the default policy evaluator for this policy.
sl@0:     LONG    policyevaluator = 0;
sl@0: 
sl@0:     // If non-zero, this field overrides the implementation UID
sl@0:     // of the default dialog creator.
sl@0:     LONG    dialogcreator = 0;
sl@0: 
sl@0:     // Flags specific to the policy evaluator
sl@0:     WORD    flags = 0;
sl@0: 
sl@0:     // Reserved for future use, do not use
sl@0:     WORD    reservedWord = 0;
sl@0: 
sl@0:     // Reserved for future use, do not use
sl@0:     LLINK   reservedLink = 0;
sl@0:     }
sl@0: 
sl@0: // Defines a set of policies and the implementations UIDs of the default
sl@0: // policy evaluator and dialog creator plug-ins.
sl@0: STRUCT POLICIES
sl@0:     {
sl@0:     // Version of the UPS policy format.
sl@0: 	// Policy files MUST NOT change this value.
sl@0:     WORD version = 1;
sl@0: 
sl@0:     // reserved for future use, do not use
sl@0:     LLINK reserved = 0;
sl@0: 
sl@0:     // A POLICY_HEADER structure
sl@0:     STRUCT header;
sl@0: 
sl@0:     // An array of POLICY structures
sl@0:     STRUCT policies[];
sl@0:     }
sl@0: 
sl@0: #endif