Home · All Classes · Grouped Classes · Annotated · Functions

SXE - System Integration

Introduction

The Safe Execution Environment - (SXE) is built into Qtopia to provide a level of confidence to allow the download and execution of native 3rd-party binaries, such as games and utilities.

At the application level, SXE acts like a firewall to prevent programs making unauthorized access to sensitive system services. Requests received by the Qtopia server are first checked to see if the originating program has the correct security domain awarded to allow the sending of such messages.

Downloaded programs must however, also be controlled at the file system level, to prevent them accessing sensitive system files, such as the sxe.policy file. Altering the policy file could result in the program awarding the security domain to itself.

These file system level controls are achieved for SXE by a Mandatory Access Control (MAC) system.

This document is to assist engineers with system integration to enable the MAC system for a device.

The MAC system for SXE is provided by the LIDS (Linux Intrusion Detection System) project: http://www.lids.org/. LIDS is discussed in the LIDS MAC kernel section below.

There are four stages to enabling the LIDS MAC system:

  1. building the LIDS enabled kernel
  2. building the LIDS user space utilities
  3. enabling LIDS during system boot and shutdown
  4. configuring the policy scripts.

These stages for enabling LIDS MAC for a Qtopia SXE device are described below.

The role of MAC in SXE

MAC policy can prevent a program from accessing the network or the modem device directly. This means that programs must route their requests via the application policy framework mentioned in the previous section.

While the SXE system will run without MAC, it requires MAC to provide a guarantee of security as the modem, policy files, and other sensitive system resources are not otherwise protected.

To reiterate, the SXE application level system continues to operate if the MAC system is not in place. However a malicious or flawed - "Malware" - program could simply alter SXE system files or directly operate on the devices hardware. The MAC system must be enabled in order for SXE to provide its level of guarantee of the security of the device.

For this reason, the Security tab of the System Information application shows the current state of SXE and whether a supported underlying MAC implementation is available.

The MAC system also provides System Hardening by the MAC bounding set. The bounding set comprises of global MAC rules which apply to all programs, unless specifically excepted. System hardening makes it much more difficult for a flawed or malicious downloaded program to compromise the device.

LIDS MAC Kernel

The Linux kernel selected for use with the device must be patched to enable support for the LIDS Mandatory Access Control (MAC) system.

LIDS kernel patches are available for both 2.4 and 2.6 series kernels. However there are some key differences between the LIDS system for the two kernel versions:

  1. LIDS for Linux 2.6 uses the Linux Security Module (LSM) framework.
  2. LIDS for Linux 2.4 includes additional features such as the Trusted Domain Enforcement (TDE) system. The TDE system makes available the LIDS_SANDBOX Access Control List rule, which simplifies the task of creating a sandbox for untrusted programs. The 2.6 series LIDS system must instead detail all rules required to effectively sandbox the untrusted program, making the list of rules required longer. Efforts are underway to port the LIDS_SANDBOX feature to the 2.6 series.

The Linux kernel patches required to enable LIDS are available from http://www.lids.org/.

A full discussion of how to patch and install the LIDS enabled kernel is beyond the scope of this document. Refer to http://www.lids.org and the documentation included in the LIDS source packages for more details.

Some resources for embedded LIDS have been prepared by a Japanese user-group.

The steps for compiling LIDS into the kernel are:

  1. Determine the Linux kernel version - here the example of 2.6.13 is used
        export SXE_ROOT=$PWD
        export LIDS=lids-2.2.1-2.6.13
        export LIDS_DL=http://qtextended.org/downloads/lids/v2.6/2.6.13
        export LIDS_DIR=$SXE_ROOT/$LIDS
  2. Download and install the LIDS patches for that version. The following assumes that the kernel sources are located in $SXE_ROOT/linux:
        wget $LIDS_DL/$LIDS.tar.gz
        tar zvxf $LIDS.tar.gz
        cd linux
        patch -p0 < ../$LIDS/$LIDS.patch
  3. Manually apply some patch hunks if required
  4. Configure the kernel as normal, ensuring that LIDS is enabled as either a module or built-in.
  5. Build Linux as normal, for example:
         make bzImage
         make modules

File System Creation

The LIDS enabled kernel requires the user space utilities /sbin/lidsconf and /sbin/lidsadm. These binaries must be installed in /sbin or LIDS will be disabled, as this path is hard-coded in the kernel.

The other components required for LIDS are the default LIDS configuration files, installed in /etc/lids.

The steps are:

  1. Prepare your file system as normal. The following assumes that the target filesystem is located at $SXE_ROOT/target.
  2. Determine cross-compile arguments if needed, for example:
         export LIDS_CROSS="--target=arm-linux --host=arm-linux --build=i586-linux-gnu"
  3. Build the LIDS MAC user space utilities
         cd $LIDS_DIR/lidstools*
         ./configure $LIDS_CROSS KERNEL_DIR=$SXE_ROOT/linux LDFLAGS=-static
         make
  4. Install the user space utilities, configuration files and LIDS kernel module into the target file system.

    Note: Here the example configuration files from the LIDS distribution are used.

         cp -u src/lidsadm src/lidsconf $SXE_ROOT/target/sbin
         export LIST=`ls -1 example/*.cap example/*.conf example/*.ini example/*.pw`
         for P in $LIST; do cp $P $SXE_ROOT/target/etc/lids; done
    
         cd $SXE_ROOT/linux
         make modules_install INSTALL_MOD_PATH=$SXE_ROOT/target

Boot Process

When a LIDS system boots, runs and shuts down, the system goes through the following stages:

  1. BOOT - special privileges available, for example, mount, fsck
  2. POSTBOOT - normal system operation
  3. SHUTDOWN - special privileges available, for example, kill, unmount

The system initialization scripts must be set up to run the command lidsadm -I at the completion of the BOOT phase. This should occur after the system initialization scripts have run to set up any mount points, networking, daemons etc. After this command, special privileges required for booting the device will be dropped, the kernel is sealed and the device is operating in secure mode.

The system shutdown scripts should likewise be setup to run the command lidsadm -S -- +SHUTDOWN at the beginning of the device shutdown or reboot sequence.

Initialization scripts must also be setup to provide the once-off LIDS initialization required, for example, via a script such as:

    if [ ! -f /etc/lids_initialized ]; then
        echo "*** First run, initializing LIDS."
        /etc/lids/sxe_boot
        lidsconf -U;
        lidsconf -C;
        lidsconf -P;
        touch /etc/lids_initialized;
    fi

Here the file /etc/lids/sxe_boot is a shell script which calls the LIDS policy file scripts mentioned in the next section, which will create the LIDS runtime rules for the device.

Policy File Creation

The resources which are required to be protected on the file system should be listed in detail before commencing creating LIDS policies. The table below can be used as a basis for constructing this list.

More general rules can be placed at the top of the table, with exceptions to the rules further down.

ItemTypical file system pathGeneral rule
system configuration/etcPrograms can read but not write
log file management/dev/log, /var/logPrograms cannot access
devices protections/dev/ttyS0, /dev/fb0 and other sensitive devicesPrograms cannot access (some programs may require access to safe character devices including)
  • /dev/zero
  • /dev/null
  • /dev/urandom
MAC system configuration/etc/lidsPrograms cannot access
Qtopia binaries/opt/Qtopia/binNo program ever launches these binaries except qpe
Qtopia libraries/opt/Qtopia/lib:/opt/Qtopia/plugins:/opt/Qtopia/qt_pluginsPrograms can read but not write
system libraries/lib:/usr/libPrograms can read but not write
system binaries/bin:/sbin:/usr/bin:/usr/sbinPrograms shouldn't be launching these binaries
Qtopia etc/opt/Qtopia/etcPrograms can read but not write. Some configuration files are not readable, see next item.
SXE registry files/opt/Qtopia/etc/keyfile, /opt/Qtopia/etc/sxe.profiles, /opt/Qtopia/etc/sxe.policy, /opt/Qtopia/etc/manifest, /opt/Qtopia/etc/keyfile.sequence, /opt/Qtopia/etc/installsNo program can read
DRM system directory/opt/Qtopia/Applications/Qtopia/DRMPrograms cannot access

Once the list has been filled out, LIDS rules can be constructed in the form of shell scripts.

    lidsconf -A -s ${BIN} -o /lib -j READONLY
    lidsconf -A -s ${BIN} -o /usr/lib -j READONLY

    lidsconf -A -s ${BIN} -o ${QTOPIA_DIR}/qt_plugins -j READONLY
    lidsconf -A -s ${BIN} -o ${QTOPIA_DIR}/services -j READONLY
    lidsconf -A -s ${BIN} -o ${QTOPIA_DIR}/etc -j READONLY

Qtopia SXE and LIDS MAC Integration Points

The LIDS MAC installation for the device is heavily dependent on the configuration of the filesystem.

In addition there are differences between the 2.6 and 2.4 series kernel implementations. Efforts are underway to reduce these differences, but at present integration by way of scripts is required in order to provide an interface for Qtopia.

This means that much of the interface between Qtopia SXE and the LIDS MAC system must be done by SXE calling into scripts which are provided by the system integration engineers for the device.

Qtopia uses this system for other integration points where device specifics prevent Qtopia code from making direct access, such as the pppd and network scripts which are called by the netsetup program.

The SXE system provides a number of scripts that can serve as a starting point for the integration effort. The scripts and descriptions of their function are listed here:

Script NameCall SignatureDescription
  • sxe_sandbox
sxe_sandbox </path/to/binary> </path/to/sandbox>Create LIDS MAC sandbox rule so that when the binary is launched it will be sandboxed to run in the directory /path/to/sandbox.

All system capabilities are denied. (Privileges such as library access is granted in the domain scripts)

Note: this script is run by the SXE packagemanager at install time, and causes policy to be written into the /etc/lids/*.conf control files.

  • sxe_unsandbox
sxe_unsandbox </path/to/binary> </path/to/sandbox>Remove LIDS rules on binary /path/to/binary.

Note: this script is run by the SXE packagemanager at uninstall time, and causes policy to be written into the /etc/lids/*.conf control files.

  • sxe_reloadconf
sxe_reloadconfReload the lids configuration so any new rules written into /etc/lids/*.conf take effect.
  • rc.lids
rc.lids start|stop|first_bootStart the LIDS system at boot-time, sealing the kernel, or at shutdown time enter SHUTDOWN mode.

This script will call other scripts mentioned below.

See the previous section on the boot process.

  • sxe_boot
sxe_bootSetup environment variables and other LIDS related initialization as a prelude to calling sxe_bounding and sxe_qtopia

This script is called by rc.lids first_boot, which occurs prior to sealing the kernel.

  • sxe_bounding
sxe_boundingSets up MAC rules for the root file system

This script is called by sxe_boot prior to generating Qtopia specific rules.

  • sxe_qtopia
sxe_qtopiaSets up MAC rules and registry files for Qtopia

This script is called by sxe_boot.

  • sxe_qtopia_<domain-name>
sxe_qtopia_<domain-name> (Various parameters are passed as environment variables including but not limited to BIN, QTOPIA_DIR and PACKAGES_DIR)Applies a set of MAC rules relevant for the domain to a specific binary.

Qtopia SXE Domain Scripts

SXE domain scripts are used to award binaries with MAC privileges based on the SXE security domain assigned to the binary. The security domain required by an application is declared in the .pro file, via either the pkg.domain or target.domain variables. For example to award an application the trusted domain, the following line can be added to the applications .pro file:

        pkg.domain += trusted

The domain scripts are executed at package install time by packagemanager. (The domain scripts do not apply to pre-installed applications). For the domain awarded to a program the associated domain script, /opt/Qtopia/etc/sxe_domains/sxe_qtopia_<domain-name>, is executed. The full path of the binary awarded the security domain is passed to the script through the BIN environment variable.

The default configuration of SXE includes two domains scripts trusted and untrusted. Applications in the trusted domain have unrestricted access to the devices hardware. Applications in the untrusted domain are only granted limited capabilities.

Setting up the security log

To setup security logging, both LIDS messages produced by the kernel and Qtopia security messages produced by qpe need to be directed to the security log.

Kernel messages (on the greenphone) have been directed to the user facility while Qtopia security messages have been directed to the local6 facility. SXE (on the greenphone) uses a customized syslogd daemon where alternate logs can be specified as extra options to syslogd like so:

    -A /mnt/documents/.log/sxe%s.log:user -A /mnt/documents/.log/sxe%s.log:local6

Log messages from both facilities will be directed to the security log so that breaches can be acted upon by the SxeMonitor.

In addition ensure that the maximum log size used by the logging facility is the same as that specified in Sxe.conf. Note that in Sxe.conf, the maximum size before rotation is specified in units of bytes, while the logging facility may use another base unit such as kilobytes.

It may be convenient to use the sxe_boot script to create the directory that will contain the security log.

Memory Limits

SXE allows limits to be placed on the memory of processes belonging downloaded applications (which applies to both trusted and untrusted programs). The limit is expressed as a proportion of the total available RAM on the device in Sxe.conf.

    [Limits]
    MaxMemRatio=0.5

In this example, any process of a downloaded application may use up to 50% of the total available RAM. This mechanism is based on the the resource limit, RLIMIT_AS. If the limit is reached, calls for memory allocation will fail with a no memory error, and if the stack tries to expand beyond the limit, the process receives a SIGSEGV signal. Bear in mind that the limit is only applied on a per process basis, a process could fork and so the total memory of consumed by the application could exceed the limit.

Troubleshooting LIDS for Greenphone

If you are trying to track down issues with LIDS on the Greenphone, the following commands may be helpful after opening up a telnet or ssh session. Enter in "greenphone" (no quotations) if asked for a password.

    lidsadm -S -- -LIDS

This makes a LIDS free session meaning that for the current session, no LIDS rules are in effect. By doing this you can view and access files that would otherwise be hidden or made read-only by LIDS. (using +LIDS instead of -LIDS turns LIDS back on for the session)

    lidsconf -L
    lidsconf -L POSTBOOT

These display the set of lids rules, note that these are not necessarily enforced, but will be the next time LIDS reloads its configuration.

    lidsconf -A -s <subject> -o <object> -j <access type>

Add a lids rule where the <subject> and <object> are the paths to files and <access type> is for example, READONLY or WRITE or DENY.

    lidsconf -D -s <subject>
    lidsconf -D -o <object>
    lidsconf -D -s <subject> -o <object>

Delete the rules for a particular subject or object, or delete the rule for a particular subject and object.

    lidsadm -S -- +RELOAD_CONF

Reloads the LIDS configuration.

    lidsadm -S -- -LIDS_GLOBAL

Turn off LIDS globally. (+LIDS_GLOBAL turns lids back on)

Note Refer to the LIDS documentation for a more comprehensive set of commands.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3