<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 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: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-5777D16D-71FA-5929-9557-4C532C59ECBF" xml:lang="en"><title>Platform
Security Considerations</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Symbian platform v9.1 introduced <xref href="GUID-4BFEDD79-9502-526A-BA7B-97550A6F0601.dita">Platform
Security</xref> (the concept of Capabilities, Signing and Data Caging) to
protect a phone against malicious code. Granting a program certain capabilities
enables it to use protected operating system functionality, and signing an
installation file enables it to be installed onto different phones. </p>
<p>A program using the P.I.P.S. libraries may need certain capabilities in
order to use protected functionality to be available. The capabilities required
are listed in the program's makefile (or an MMP file on the Symbian
platform). For example, the following line added to a Symbian MMP file will
grant network access to a program. </p>
<codeblock id="GUID-4D511177-F8F2-56A1-AB6C-91B3B1F04FE5" xml:space="preserve">CAPABILITY     NetworkServices</codeblock>
<p>Each Symbian program has access to a private area of storage in a <filepath>/private/&lt;secureid&gt;/</filepath> directory
where <codeph>secureid</codeph> is an identifier specified in the MMP file.
If a <codeph>secureid</codeph> is not specified in the MMP file, the <codeph>secureid</codeph> is
set from the program's third UID (Unique Identifier). Some extra capabilities
are required if the program wishes to have access to another program's private
area. Also it is worth noting that P.I.P.S. does not allow file descriptors
in private directories to be inherited. </p>
<section id="GUID-A4D36A90-314A-5EEA-A025-7135A9A60177"><title>Capabilities
supported for P.I.P.S. APIs</title> <p>The following table provides details
of the P.I.P.S. APIs and the capabilities that may need to be added. </p> <table id="GUID-4DF992C4-AE1E-56BC-B97F-BC411D02E3FF">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <b>P.I.P.S. API</b>  </p> </entry>
<entry><p> <b>Capabilities required</b>  </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-D926453F-9D3F-3604-B6E1-9782C3779DDF.dita"><apiname>lstat()</apiname></xref>, <xref href="GUID-A89FA772-80F2-39E8-AEFB-B9B4E833A1FA.dita"><apiname>stat()</apiname></xref>, <xref href="GUID-BEE67FC6-54F4-3711-B367-87EF751472A7.dita"><apiname>tmpnam()</apiname></xref>, <xref href="GUID-C8EA1CF0-D221-3A9D-84B1-5ED8A6DA933F.dita"><apiname>tempnam()</apiname></xref>, <xref href="GUID-875BC63B-B23B-374C-A932-24701D8C8220.dita"><apiname>wstat()</apiname></xref>  </p> </entry>
<entry><p> <codeph>None</codeph> if the path is not in the protected /sys/
or /private/ directory. </p> <p> <codeph>AllFiles</codeph> if the path contains
the protected /sys/ directory. </p> <p> <codeph>AllFiles</codeph> if the path
contains the protected /private/ directory using another program's Secure
Identifier. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-A9330ABF-23DD-3DAE-BCB5-1B2448EF34E3.dita"><apiname>open()</apiname></xref>, <xref href="GUID-FA8FEC6E-622F-3F06-B15F-7B9769616149.dita"><apiname>wfopen()</apiname></xref>  </p> </entry>
<entry><p> <codeph>None</codeph> if the path is not in the protected /sys/
or /private/ directory. </p> <p> <codeph>AllFiles</codeph> if the path contains
the protected /sys/ directory and read mode is specified. </p> <p> <codeph>TCB</codeph> if
the path contains the protected /sys/ directory and write mode is specified.
P.I.P.S. libraries do not have the TCB capability, and so it is not possible
to write to this directory. </p> <p> <codeph>AllFiles</codeph> if the path
contains the protected /private/ directory using another program's Secure
Identifier. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-9AE17F91-D9F7-3DD5-8D6C-AC6BDD0BBF7D.dita"><apiname>access()</apiname></xref>, <xref href="GUID-96A8BB01-07F4-3701-8390-858E47B11068.dita"><apiname>chdir()</apiname></xref>, <xref href="GUID-F5DE6335-1C8B-31F6-A70F-DCA12C050836.dita"><apiname>chmod()</apiname></xref>, <xref href="GUID-7AE53522-A016-3CF2-9394-38A65A628FDF.dita"><apiname>creat()</apiname></xref>, <xref href="GUID-D441A5DF-C7B8-38A7-B386-62DB47D95DE2.dita"><apiname>fchmod()</apiname></xref>, <xref href="GUID-A745D453-FD35-36AC-B2A6-1B118FC0ECE7.dita"><apiname>ftok()</apiname></xref>, <xref href="GUID-5EA72F64-E826-3B15-9468-902BD57F6AA7.dita"><apiname>mkdir()</apiname></xref>, <xref href="GUID-F4749DAA-1B29-3D1D-A3AA-0D52B851E501.dita"><apiname>mkfifo()</apiname></xref>, <xref href="GUID-28E8C6E1-93F6-326B-8B10-6EFCC19A71B8.dita"><apiname>rename()</apiname></xref>, <xref href="GUID-0A4E12DC-191F-3093-8FCC-1F09BC057EF8.dita"><apiname>rmdir()</apiname></xref>, <xref href="GUID-D8A63E18-878B-3AD4-863D-269E974ED8B2.dita"><apiname>utimes()</apiname></xref>, <xref href="GUID-7F392C01-C20D-3625-A964-F41BB925A5CC.dita"><apiname>waccess()</apiname></xref>, <xref href="GUID-13413FF7-5CAB-38DB-97FC-A4E45E076696.dita"><apiname>wchdir()</apiname></xref>, <xref href="GUID-48438139-E717-3E86-ACD4-E81D6482B659.dita"><apiname>wcreat()</apiname></xref>, <xref href="GUID-F173F204-ECCE-3FC8-B3BF-4F58513A7D0C.dita"><apiname>wmkdir()</apiname></xref>, <xref href="GUID-16518B7B-C146-32E6-9360-A4EEF268CA98.dita"><apiname>wrmdir()</apiname></xref>, <xref href="GUID-F33C1971-5E72-331A-B699-CC32D36B7584.dita"><apiname>wunlink()</apiname></xref>, <xref href="GUID-5F612E71-362E-37D8-A457-8AF1AB545496.dita"><apiname>unlink()</apiname></xref>, <xref href="GUID-234DE8F8-1D41-3BE0-980B-37ACF281DDA6.dita"><apiname>utime()</apiname></xref>  </p> </entry>
<entry><p> <codeph>None</codeph> if the path is not in the protected /sys/,
/resource/ or /private/ directory. </p> <p> <codeph>TCB</codeph> if the path
contains the protected /sys/ or /resource/ directory. P.I.P.S. libraries do
not have the TCB capability, and so it is not possible to write to this directory. </p> <p> <codeph>AllFiles</codeph> if
the path contains the protected /private/ directory using another program's
Secure Identifier. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-8B08EBCD-937C-3704-8E6A-08A45881F70D.dita"><apiname>accept()</apiname></xref>, <xref href="GUID-DD961B2B-AAEE-3A83-81E2-0B9F7BE58BE6.dita"><apiname>bind()</apiname></xref>, <xref href="GUID-B1E46044-267D-3F35-9712-F1A0D7E8F03F.dita"><apiname>connect()</apiname></xref>, <xref href="GUID-F923CE02-3850-3494-95FE-094506318F10.dita"><apiname>ioctl()</apiname></xref>, <xref href="GUID-4BE12A23-0E4D-37CC-891C-6B9931CA2E7A.dita"><apiname>recv()</apiname></xref>, <xref href="GUID-45F73DAA-7E14-307A-BE55-FFCAEA898A86.dita"><apiname>recvfrom()</apiname></xref>, <xref href="GUID-0D328B4A-15D0-36EB-B92E-E285A11F1ABC.dita"><apiname>send()</apiname></xref>, <xref href="GUID-2E55A695-EE36-37F3-A088-2BA282B8EA9F.dita"><apiname>sendto()</apiname></xref>, <xref href="GUID-CCE203C4-7985-3FF7-829B-CF3873D62098.dita"><apiname>recvmsg()</apiname></xref>, <xref href="GUID-F580A280-7797-3D55-B1C3-1CACC0429830.dita"><apiname>sendmsg()</apiname></xref>  </p> </entry>
<entry><p> <codeph>None</codeph> if the descriptor does not refer to a socket. </p> <p> <codeph>NetworkServices</codeph> if
the descriptor is a socket. </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
<example><title>A P.I.P.S. platform security example</title> <p>The following
code illustrates how P.I.P.S. conforms to Data Caging rules while creating
a file with and without capabilities. </p> <codeblock id="GUID-680669E9-0261-5A1C-9A20-67A5148C440B" xml:space="preserve">#include &lt;stdio.h&gt;

int main(int argc, char *argv[])
{
   FILE* file;
   
   //Create the file in another program's private directory
   file = fopen("/private/10004902/out.file", "w");
   if (file == NULL)
   {
      int I = errno;
   
      //Error occurred
      printf("\nError creating file, error=%d", errno);    
      return EXIT_FAILURE;
   }
   else
   {
      //File created
      fprintf(file, "Sample File Output");
      fclose(file);
      
      printf("\nFile created");    
   }

   return EXIT_SUCCESS;
}</codeblock> <p>If no capabilities are provided, the code will print out
an error message due to the attempted use of <xref href="GUID-64886CC6-072F-3542-855A-5D733FC761E8.dita"><apiname>fopen()</apiname></xref> on
another program's <filepath>/private/</filepath> directory. The error code
displayed will be <xref href="GUID-3148D2B9-FF17-35E1-A74B-50EBF1B79679.dita"><apiname>EACCESS</apiname></xref>, showing a security error. </p> <p>If,
however, the <codeph>AllFiles</codeph> capability is listed in the program's
MMP file, the file will be generated successfully. </p> <p> <b>Note:</b> Here, <codeph>AllFiles</codeph> represents
a system capability and is not something your application should require or
use, in most of the cases. </p> </example>
</conbody></concept>