» Symbian OS » Developer Knowledgebase

Classification:	C++	Category:	Development
Created:	11/15/2005	Modified:	11/28/2005
Number:	FAQ-1340
Platform:	Symbian OS v9, Symbian OS v9.0, Symbian OS v9.1, Symbian OS v9.2

Question:
How do I debug Platform Security API policy violations?
What are Platform Security API policy violations?

Answer:
What are Platform Security API policy violations?
A Platform Security API policy violation occurs when a process calls an API for which it does not have a required capability. In most cases the API will return (or Leave) with the error code KErrPermissionDenied (-46). The error may propagate up to the UI in a standard error dialog box (UI dependent).

In order to use the API/avoid the error, the process must specify the required capability in its MMP file at build time, using the CAPABILITY keyword. See:
» Symbian OS v9.1 » Symbian OS Tools And Utilities » Build tools reference » mmp file syntax » capability

Notes:

You can specify any/all capabilities at build time in your MMP file. However if your executable is to be delivered in a SIS file you will need to justify the requested capabilities to Symbian Signed (see the Test Criteria document at https://www.symbiansigned.com/app/page/requirements). Unsigned SIS files that use anything other than the basic capabilities will not install.
The requirement for signing does not affect binaries in ROM (or on the Emulated Z drive), so you do not need to worry about "signing" while developing on the Emulator or on a development board where you have built the ROM.
Before finally assigning a capability to process, first assess whether the process should be calling the API in question (at all). There may be an unrestricted higher-level/intrinsically less dangerous API that should be used instead of the capability restricted API. See the Platform Security Engineering guide in the Symbian OS Developer Library for more information:
» Symbian OS v9.1 » Symbian OS guide » Platform security

How do I debug Platform Security API policy violations?
If you know the API call that is causing the KErrPermissionDenied error, you can determine the capability to specify in your MMP file from the Symbian Developer Library. For example, to find the capability required for CContactDatabase::CreateL, search on "capability CContactDatabase::CreateL" in the HTMLHELP (CHM) version of the Developer Library.

Where specific API information is not available, or for situations where you merely suspect that a platsec violation may be occurring, PlatSecDiagnostics can be used to determine the required capability.

PlatSecDiagnostics can be enabled and obtained on the Emulator, as described in FAQ 1344: "How do I Enable Platform Security Diagnostics on the Symbian OS Emulator?".

PlatSecDiagnostics messages are output to the default output location of RDebug::RPrint() calls. You can discriminate the PlatSecDiagnostics notifications from other debug information by searching for log lines preceeded by *PlatSec*

For example, a PlatSecDiagnostics error has the following appearance:

*PlatSec* ERROR - Capability check failed - A Message (function number=0x000000cf) from Thread helloworld[10008ace]0001::HelloWorld, sent to Server !CntLockServer, was checked by Thread CNTSRV.EXE[10003a73]0001::!CntLockServer and was found to be missing the capabilities: WriteUserData . Additional diagnostic message: Checked by CPolicyServer::RunLThis message contains enough information to identify the source of the policy violation "HelloWorld", the server called "CNTSRV.EXE" (the contacts server) and most importantly, the missing capability "WriteUserData".
The actual API called is not obvious (In this instance, CContactDatabase::CreateL), however standard debugging techniques (analysing source, added extra traces to return codes) should reveal which API it is, if required.

Notes:

PlatSecDiagnostics are not available on production phones based on current versions of Symbian OS (i.e. at least until Symbian OS v9.2). Therefore aftermarket developers should use the Emulator for this purpose.
DevKit licensees can also get diagnostics on reference boards, as defined in the Platinum Partner Extranet FAQ 1341: "How do I Enable Platform Security Diagnostics on Symbian OS Target Hardware?".

Related Information

DevKit licensees may also refer to the document:
/src/cedar/generic/base/documentation/Base_How_To_Configure_Platform_Security_Settings.doc