Home · All Classes · Annotated · Functions

SXE - System Integration

• Introduction
• The role of LIDS MAC in SXE
• LIDS MAC kernel
• File System Creation
• Boot Process
• Policy File Creation
• Qtopia SXE and LIDS MAC integration points
• Qtopia SXE domain scripts
• Qtopia 4.1 Release Pending Functionality

Introduction

From Qtopia 4.1 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 for the Qtopia phone 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 Instruction Detection) project: http://lids.org. LIDS is discussed in the LIDS MAC kernel section below.

There are three stages to enabling the LIDS MAC system:

1. building the LIDS kernel
2. building the LIDS file system
3. configuring the policy scripts.

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

The role of LIDS 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 LIDS 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 LIDS MAC system must be enabled in order for SXE to provide its level of guarantee of the security of the device.

For this reason, if the LIDS system is detected in the underlying device then the Qtopia System Information application will show that SXE is enabled - otherwise it will show in red that SXE is disabled.

The MAC system also provides System Hardening by the MAC bounding set. The bounding set comprises 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 the LIDS Mandatory Access Control (MAC) system.

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

1. If the kernel is a 2.6 series, the LIDS system can be compiled as a module and inserted after the kernel has booted. This is because 2.6 patch sets use the Linux Security Module (LSM) framework. The 2.4 series LIDS system must be compiled in to the kernel, and run from boot.
2. For 2.4 series LIDS systems, the LIDS_SANDBOX Access Control List rule is available as part of the LIDS Trusted Domain Enforcement system. This rule makes it simpler to sandbox 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 at: http://lids.org.

A full discussion of how to patch and install the LIDS enabled kernel is beyond the scope of this document. Refer to the LIDS Wiki for more details.

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

The steps to compiling lids into the kernel are:

• Determine the kernel version - here the example of 2.6.13 is used
• The following assumes kernel sources are in $PWD/linux:

      export SXE_ROOT=$PWD
      export LIDS=lids-2.2.1-2.6.13
      export LIDS_DL=http://www.lids.org/download/v2.6/2.6.13
      export LIDS_DIR=$PWD/$LIDS

• Download and install the LIDS patches for that version:

      wget $LIDS_DL/$LIDS.tar.gz
      tar zvxf $LIDS.tar.gz
      cd linux
      patch -p0 < ../$LIDS/$LIDS.patch

• manually apply some patch hunks if required
• configure the kernel as normal
• ensure LIDS is enabled in the .config - set LIDS be a module if desired
• build Linux as normal

       make linux ARCH=<some arch>
       make modules ARCH=<some arch>

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 - assume it is mounted at $SXE_ROOT/target
2. Determine your cross-compile arguments if needed

        export LIDS_CROSS="--target=arm-linux --host=arm-linux --build=i586-linux-gnu"

3. Building the LIDS MAC userspace tools

        cd $LIDS_DIR/lidstools*
        ./configure $LIDS_CROSS KERNEL_DIR=../../$LINUX LDFLAGS=-static
        make

4. install the tools, configuration files and other items in the file-system

   Note: here the example configuration files from the LIDS distribution are used

        cp -u src/lidsadm src/lidsconf target_mnt/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=target_mnt ARCH=um

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
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 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, initialising lids."
        /etc/lids/lids.conf.sh
        lidsconf -U;
        lidsconf -C;
        lidsconf -P;
        touch /etc/lids_initialized;
    fi

Here the file /etc/lids/lids.conf.sh 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.

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

    lidsconf -A -o /etc -j READONLY
    lidsconf -A -s /opt/Qtopia/bin/qpe -o /etc/network -j WRITE

    lidsconf -A -o /etc/lids -j DENY
    lidsconf -A -s /sbin/lidsconf -o /etc/lids -j READONLY
    lidsconf -A -s /sbin/lidsconf -o /etc/lids/lids.cap -j READONLY
    lidsconf -A -s /sbin/lidsconf -o /etc/lids/lids.conf -j READONLY

    lidsconf -A -o /opt/Qtopia/bin -j DENY
    lidsconf -A -s /opt/Qtopia/bin/qpe -o /opt/Qtopia/bin -j READONLY
    lidsconf -A -o /opt/Qtopia/bin -j DENY
    lidsconf -A -s /opt/Qtopia/bin/netsetup -o /opt/Qtopia/bin -j READONLY

    lidsconf -A -o /opt/Qtopia/etc -j READONLY
    lidsconf -A -o /opt/Qtopia/etc/keyfile -j DENY
    lidsconf -A -s /opt/Qtopia/bin/qpe -o /opt/Qtopia/etc/keyfile WRITE

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 - examples are the pppd and network scripts which are called by the netsetup program, and the card monitor facility provided during integration which tells Qtopia when a new storage media card has been inserted.

The SXE system provides a number of script templates to assist in the integration effort. The scripts and descriptions of their function are listed here:

Qtopia SXE domain scripts

Where special access is required for applications based on the security domains awarded, an sxe domain script is created.

When the packagemanager installs a program with security domains, for each domain the directory /opt/Qtopia/etc/sxe_domains is scanned for a script with the name sxe_qtopia_<domain-name>.sh where the <domain-name> is the actual name of the domain.

For example sxe_qtopia_drm.sh provides access for applications with the drm domain to the drm system directory:

    lidsconf -A POSTBOOT -s ${BIN} -o /opt/Qtopia/Applications/Qtopia/DRM -j WRITE

Lines in the file are token substituted with ${BIN} being replaced by the installed location of the binary, then the contents of the file are concatenated to the end of the /opt/Qtopia/etc/sxe_qtopia/sxe_qtopia_<binary-name>.sh script.

This script is then run to create the LIDS policy for that program.

Note that with the drm domain, and with most domains which require LIDS privileges, only Qtopia system programs delivered as part of a system upgrade or system update would be awarded such a domain. Downloaded 3rd party applications should rarely if ever require such policies.

The same mechanism is used by the sxe_installer program to install lids scripts at make install time. The sxe domains are listed in the .pro files for each Qtopia program under the pkg.domains variable.

For each of these domains, the sxe_installer processes the scripts described above, just as the packagemanager would during normal operation, and adds to the scripts listed in the /opt/Qtopia/etc/sxe_qtopia directory.

When the Qtopia SXE device boots up, during the initialization process the sxe_boot.sh script is run. See the previous section for more details of how this script is called.

One of the actions of this script is to call the run-parts command (provided by BusyBox on devices) on the /opt/Qtopia/etc/sxe_qtopia directory if the sxe system requires initialization.

Qtopia 4.1 Release Pending Functionality

Items not completed for the 4.1 Release include the *.template script files mentioned in the previous section.

These will be provided in the upcoming maintenance release.

Also the Qtopia SXE functionality in the packagemanager which would call into these scripts has not been completed as it relies on these scripts.

The sxe_qtopia scripts covered in the previous section, and the make install and packagemanager functionality which implements it has also not yet been completed.