Policy -Resource

Policies resource structure

A policy resource is -made up of the following; a header, followed by any number of policies. Policies -need to be ordered from most specific to least specific.

There are -two ways to control whether prompts are generated for system servers:

Using the authorisationpolicy setting -in the header. If authorisationpolicy is set to anything -except EAlwaysCheck, prompts will not be generated for Messaging -Server, Java VM etc because these components are in the ROM, have the appropriate -capabilities and have protected secure ids.
Using the SID_LIST setting -in the policy. The SID_LIST can be used to create a very -specific policy that always allows requests from trusted components as in -the example policy below.

Header

The header includes the following possible -fields: majorversion, minorversion, authorisationpolicy, dialogcreator and policyevaluator.

The major version number controls whether -existing decision records for services corresponding to the policy file are -deleted or preserved when the policy file is upgraded.

The authorisationpolicy field -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. The value for authorisationpolicy can be one of the -following:

- - - -

EAlwaysCheck

Ignore the system server (platsec) checks and always ask the UPS -what to do.

- - -

ECheckPostManufacture

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.

- - -

ECheckUnprotectedSids

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.

- - -

ECheckIfFailed

If the system server checks passed, allow the request. If they failed, -call the UPS which may still choose to allow the request.

- - -

ENeverCheck

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. (This is the legacy pre-UPS -behaviour.)

- - - -

If no authorisationpolicy is provided, the default -is ECheckPostManufacture.

Note: If a policy -file is not defined for a system server or service then a default value of ENeverCheck is -used.

The dialogcreator must be provided and must -not be zero. In the policy file it is the only field that is actually required. -The policyevaluator can be specified here, but if one is -not specified, a default policy evaluator is called. The dialogcreator and policyevaluator UIDs -are allocated by Symbian Signed. They are the implementation UIDs of the relevant -ECOM plugins.

The following shows an example header:

header = 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. - majorversion = 0; - // The minor version number of THIS policy file. - minorversion = 0; - - // Built-in (protected SID and loaded from Z drive) client applications - // do not require authorisation from the UPS if the client has the correct - // capabilities. - authorisationpolicy = ECheckPostManufacture; - //dialogcreator and policyevaluator UIDs - dialogcreator = 0x10283694; - policyevaluator = 0x10283698; - }; -

Policies

Policies can have the following optional -fields:

- - - -

Field

Description

Possible values

- - -

sid_classes

A bitmask that defines the set of SID classes that this policy applies -to. It is ignored if a sid_list[] field is provided.

KProtectedSids (All clients with a protected SID) KUnprotectedSids (All -clients with an unprotected SID) KAllSids (All clients)

(Defined -in ups/policies.rh.)

- - -

sid_list[]

An array of LONGs that defines a set of specific client application -SIDs that this policy applies to.

<Application SID>, <Application SID>, …

- - -

systemserversecurity

Allows policies to be matched according to whether the client process -passed the 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.

ESystemServerSecurityPassedOrFailed (The policy -applies regardless of whether the client process passed the system server's -security check.)

ESystemServerSecurityFailed (The -policy only applies if the client process failed the system server's security -check.)

ESystemServerSecurityPassed (The policy -only applies if the client process passed the system server's security check.)

(Defined -in ups/policies.rh.)

- - -

destination

A string to match against the destination supplied by system server.

“<STRING>” (e.g. telephone number) or “*” for all (The default -value is "*" and the matching rules are those of TDesC::MatchF, -so it is a case-insensitive wildcard match.)

- - -

options

A bit field to control which buttons to display on the dialog.

KYes, KNo, KSessionYes, KAlways, KNever, KSessionNo

KSessionNo should be used with care because it -is likely that a system server will define a session to be the life-time of -the client process. Consequently, the client application would have to be -restarted in order to gain access to the service. This makes it difficult -to write a well-behaved application that switches between on-line and off-line -modes.

(Defined in ups/policies.rh.)

- - -

policyevaluator

If non-zero, overrides the implementation UID of the policy evaluator -defined in the header.

<UID>

- - -

dialogcreator

If non-zero, overrides the implementation UID of the dialog creator -defined in the header.

<UID>

- - -

flags

Flags specific to the policy evaluator. Can be used to trigger specific -behaviour.

<16-bit number>

- - - -

Note: If the matched policy defines only positive options (Yes, -Session or Always), the UPS silently instructs the system server to allow -the request. If the matched policy defines only negative options (No -or Never), the UPS silently instructs the system server to reject the request. -It is usually better not to configure UPS policies to silently reject requests -because it is likely to cause the client application to fail without warning. -Instead, the policy could restrict requests to one-shot permissions (Yes or -No).

Matching policies

The UPS compares each policy -within a file in order, starting with the first policy in the file, against -the incoming request until a match is found. The match is based on the secure -id of the client application, the destination of the request (e.g. Phone number, -Access Point) and whether the client passed the system server's platform security -check. All three elements must match (wildcards are supported) the data in -the request before the policy is considered a match.

You can use the sid_list and destination fields -to fine-tune your policies, by providing specific application UIDs in sid_list and -specific destinations, such as one telephone number, in destination.

Because -the UPS compares incoming requests against policies in order, the UPS requires -that all of the policies for a given service are ordered from most specific -to least specific in a single policy file. Only the first policy that matches -is evaluated. So if, for example, you need to provide specific behaviour for -one application that falls into the category KProtectedSids as -well as providing more general behaviour for all other applications falling -into the KProtectedSids category, you need to define the -policy for the individual application first. Likewise, if you need to provide -behaviour for one particular destination but another behaviour for all other -destinations, you need to specify the policy for the specific destination -first.

Default policies

If a UPS policy -file exists for a system server/service but no policy matches the request, -the UPS internally creates a default policy object that is passed to the Policy -Evaluator and Dialog Creator. This policy object allows one-shot permissions -for applications, which will already have got past the platform security check. -Policy file authors may override this by defining a generic policy to match -all requests at the end of the policy file.

See also

Writing -the UPS Policy File

+ + + + + +Policy +Resource +

Policies resource structure

A policy resource is +made up of the following; a header, followed by any number of policies. Policies +need to be ordered from most specific to least specific.

There are +two ways to control whether prompts are generated for system servers:

Using the authorisationpolicy setting +in the header. If authorisationpolicy is set to anything +except EAlwaysCheck, prompts will not be generated for Messaging +Server, Java VM etc because these components are in the ROM, have the appropriate +capabilities and have protected secure ids.
Using the SID_LIST setting +in the policy. The SID_LIST can be used to create a very +specific policy that always allows requests from trusted components as in +the example policy below.

Header

The header includes the following possible +fields: majorversion, minorversion, authorisationpolicy, dialogcreator and policyevaluator.

The major version number controls whether +existing decision records for services corresponding to the policy file are +deleted or preserved when the policy file is upgraded.

The authorisationpolicy field +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. The value for authorisationpolicy can be one of the +following:

+ + + +

EAlwaysCheck

Ignore the system server (platsec) checks and always ask the UPS +what to do.

+ + +

ECheckPostManufacture

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.

+ + +

ECheckUnprotectedSids

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.

+ + +

ECheckIfFailed

If the system server checks passed, allow the request. If they failed, +call the UPS which may still choose to allow the request.

+ + +

ENeverCheck

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. (This is the legacy pre-UPS +behaviour.)

+ + + +

If no authorisationpolicy is provided, the default +is ECheckPostManufacture.

Note: If a policy +file is not defined for a system server or service then a default value of ENeverCheck is +used.

The dialogcreator must be provided and must +not be zero. In the policy file it is the only field that is actually required. +The policyevaluator can be specified here, but if one is +not specified, a default policy evaluator is called. The dialogcreator and policyevaluator UIDs +are allocated by Symbian Signed. They are the implementation UIDs of the relevant +ECOM plugins.

The following shows an example header:

header = 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. + majorversion = 0; + // The minor version number of THIS policy file. + minorversion = 0; + + // Built-in (protected SID and loaded from Z drive) client applications + // do not require authorisation from the UPS if the client has the correct + // capabilities. + authorisationpolicy = ECheckPostManufacture; + //dialogcreator and policyevaluator UIDs + dialogcreator = 0x10283694; + policyevaluator = 0x10283698; + }; +

Policies

Policies can have the following optional +fields:

+ + + +

Field

Description

Possible values

+ + +

sid_classes

A bitmask that defines the set of SID classes that this policy applies +to. It is ignored if a sid_list[] field is provided.

KProtectedSids (All clients with a protected SID) KUnprotectedSids (All +clients with an unprotected SID) KAllSids (All clients)

(Defined +in ups/policies.rh.)

+ + +

sid_list[]

An array of LONGs that defines a set of specific client application +SIDs that this policy applies to.

<Application SID>, <Application SID>, …

+ + +

systemserversecurity

Allows policies to be matched according to whether the client process +passed the 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.

ESystemServerSecurityPassedOrFailed (The policy +applies regardless of whether the client process passed the system server's +security check.)

ESystemServerSecurityFailed (The +policy only applies if the client process failed the system server's security +check.)

ESystemServerSecurityPassed (The policy +only applies if the client process passed the system server's security check.)

(Defined +in ups/policies.rh.)

+ + +

destination

A string to match against the destination supplied by system server.

“<STRING>” (e.g. telephone number) or “*” for all (The default +value is "*" and the matching rules are those of TDesC::MatchF, +so it is a case-insensitive wildcard match.)

+ + +

options

A bit field to control which buttons to display on the dialog.

KYes, KNo, KSessionYes, KAlways, KNever, KSessionNo

KSessionNo should be used with care because it +is likely that a system server will define a session to be the life-time of +the client process. Consequently, the client application would have to be +restarted in order to gain access to the service. This makes it difficult +to write a well-behaved application that switches between on-line and off-line +modes.

(Defined in ups/policies.rh.)

+ + +

policyevaluator

If non-zero, overrides the implementation UID of the policy evaluator +defined in the header.

<UID>

+ + +

dialogcreator

If non-zero, overrides the implementation UID of the dialog creator +defined in the header.

<UID>

+ + +

flags

Flags specific to the policy evaluator. Can be used to trigger specific +behaviour.

<16-bit number>

+ + + +

Note: If the matched policy defines only positive options (Yes, +Session or Always), the UPS silently instructs the system server to allow +the request. If the matched policy defines only negative options (No +or Never), the UPS silently instructs the system server to reject the request. +It is usually better not to configure UPS policies to silently reject requests +because it is likely to cause the client application to fail without warning. +Instead, the policy could restrict requests to one-shot permissions (Yes or +No).

Matching policies

The UPS compares each policy +within a file in order, starting with the first policy in the file, against +the incoming request until a match is found. The match is based on the secure +id of the client application, the destination of the request (e.g. Phone number, +Access Point) and whether the client passed the system server's platform security +check. All three elements must match (wildcards are supported) the data in +the request before the policy is considered a match.

You can use the sid_list and destination fields +to fine-tune your policies, by providing specific application UIDs in sid_list and +specific destinations, such as one telephone number, in destination.

Because +the UPS compares incoming requests against policies in order, the UPS requires +that all of the policies for a given service are ordered from most specific +to least specific in a single policy file. Only the first policy that matches +is evaluated. So if, for example, you need to provide specific behaviour for +one application that falls into the category KProtectedSids as +well as providing more general behaviour for all other applications falling +into the KProtectedSids category, you need to define the +policy for the individual application first. Likewise, if you need to provide +behaviour for one particular destination but another behaviour for all other +destinations, you need to specify the policy for the specific destination +first.

Default policies

If a UPS policy +file exists for a system server/service but no policy matches the request, +the UPS internally creates a default policy object that is passed to the Policy +Evaluator and Dialog Creator. This policy object allows one-shot permissions +for applications, which will already have got past the platform security check. +Policy file authors may override this by defining a generic policy to match +all requests at the end of the policy file.