Home · All Classes · Grouped Classes · Annotated · Functions

QPackageRegistry Class Reference

The QPackageRegistry class provides a mechanism for managing software installed on the qtopia device More...

    #include <QPackageRegistry>

Inherits QObject.

Public Types

Public Functions

Public Slots

Static Public Members

Additional Inherited Members


Detailed Description

The QPackageRegistry class provides a mechanism for managing software installed on the qtopia device

QPackageRegistry provides several methods for managing the database files which track installed software as part of the Safe Execution Environment (SXE).

When downloaded software is installed the SXE Software Installer calls methods here, to register the software with SXE and thus enable SXE for those applications, and to allow later uninstallation.

Program Management

All programs installed on the device are assigned a program id. A program will often consist of a number of binaries providing related functionality, for example a game may contain a small server, a gui client and a map editor which make up the package. In Qtopia, binaries which provide similar functionality and require the same security domain, are grouped into one program id.

The program id is always written into the binary at install time, along with a secret key.

For Qtopia programs when the image is created the sxe_installer is run which calls the packageRegistry in bootstrap mode to setup the database files and install the program id, and keys for those Qtopia programs. This occurs prior to shipping & delivery of the Qtopia device.

For downloaded programs the package installer will call the registerBinary() method to install the program id. This occurs during normal runtime of the Qtopia device.

When the program id and key is created and installed, these are recorded in the Keyfile, and the Sequence file is used to track issue of new program ids.

Note that rekeying and key time-outs are no longer used. This mechanism has been superseded by the /proc/lids/keys method.

See Key File Change Notes for important details on these changes.

Binary Management

Installed binaries by inode & device id are mapped to their program id in the Manifest file. Many binaries can map to a single program id.

This format is designed for fast lookup of programs. Given a binary's path, eg from /proc/<pid>/exe, the inode and device id could be obtained, and the correct program id read from this file.

The manifest file is only accessed by the packagemanager and the server (qpe). Its contents are not as sensitive as the keyfile, but should not be accessible by other processes.

If the string version of the paths for a binary are needed based on install id, they can be looked up in the Installs file. This is required mainly for uninstallation of packages, but could be used for reporting and other purposes.

The manifest and installs files are accessed by the packagemanager and the server (qpe). Their contents are not as sensitive as the keyfile, but should not be accessible by other processes.

SXE Package Database Files

As discussed in the previous two sections, QPackageRegistry tracks several files which comprise the SXE database. This table summarizes these files and their format:

KeyfileSequenceManifestInstalls
$QPEDIR/etc/keyfile$QPEDIR/etc/keyfile.sequence$QPEDIR/etc/manifest$QPEDIR/etc/installs
Pseudo-code for binary file data record formats: See $QT_SOURCE_PATH/src/gui/embedded/qtransportauth_qws_p.h for concrete details. usr_key_entry is from the kernel file include/linux/lidsext.h and is duplicated in the qtransportauth_qws_p.h
    struct usr_key_entry
        char key[QSXE_KEY_LEN];
        ino_t ino;              // typically 4 bytes
        dev_t dev;              // typically 8 bytes
    struct AuthRecord
      16 byte key
      program id
      change time   // deprecated
    struct IdBlock
        quint64 inode
        quint64 device
        unsigned char progId
        unsigned short installId
        unsigned int keyOffset
        qint64 install_time
    install record
        install id
        ":"
        path
Contains the mapping between keys and files on disk.

When the kernel contains the LIDS MAC Trolltech patch the key file is implemented as the kernel /proc pseudo-file /proc/lids/keys.

In this case this keyfile on disk storage is ignored.

This file is used simply to ensure a sequence of program id numbers.

For historical and compatibility reasons, the first key issued with a number and the time are also recorded in this file.

Map Installed binaries by inode & device id to their program id - many binaries can map to a single program id. Records an install id for each binary.Map install id to installed path of the binary.

This is required mainly for uninstallation of packages.

To query these files after a make install use the tool $QTOPIA_SOURCE_PATH/scripts/dumpsec.pl

Key File Change Notes

Both the proc pseudo file and the disk file have the same format, and if the /proc/lids/keys file is not present, disk files are used instead.

The struct usr_key_entry is defined in SXE kernel patch file include/linux/lidsif.h

struct usr_key_entry is the (new) data record format for the key file superseding the format used in Qtopia 4.1

The key file is (now) either /proc/lids/keys (and the per-process keys in /proc/<pid>/lids_key ) OR for desktop/development ONLY (not for production) it is $QPEDIR/etc/keyfile

The key file maps keys to files.

File are identified by inode and device numbers, not paths.

(See the "installs" file for path to inode/device mapping)

Disk keyfiles are to allow desktop development and testing only, since on desktop development machines the kernel patch will typically not be installed.

It is not supported on the device to operate without /proc/lids/keys

Where binary files are writeable (all downloaded programs must be writeable) the key is embedded in the binary at install time.

In the development and testing case, the embedded key is used by the binary to authenticate itself to the server.

When the kernel contains the LIDS MAC Trolltech patch the binary reads its key from the /proc pseudo-file /proc/self/lids_key.

See also RegistryFile.


Member Type Documentation

enum QPackageRegistry::RegistryFile

This enum specifies one of the registry files

ConstantValueDescription
QPackageRegistry::Keyfile0keyfile
QPackageRegistry::Manifest2manifest keyfile
QPackageRegistry::KeyfileSequence1key file
QPackageRegistry::Installs3installs file
QPackageRegistry::Policy4policy file


Member Function Documentation

QPackageRegistry::QPackageRegistry ()

Construct new QPackageRegistry object

Do not use this method, instead call the instance method getInstance()

See also getInstance().

QPackageRegistry::~QPackageRegistry ()   [virtual]

Destroy the QPackageRegistry object

int QPackageRegistry::bootstrap ( const QString & installRoot )

Bootstrap the qtopia image with sxe control files.

Creates (or truncates) new empty SXE control files, ready to be updated by the scanner. If the installRoot already contains non-empty files then it will refuse to overwrite them.

The return code of this is used as a unix exec return code, ie 0 is success non-zero is failure.

const unsigned char * QPackageRegistry::getClientKey ( unsigned char progId )

Return the key associated the specified program id progId.

As a host binary sxe_installer doesnt have access to this method in qtransportauth_qws.cpp, so reimplement it here.

In the SXE installer case assume there is a one-to-one mapping from keys to progId's since the installer ensures that.

QPackageRegistry * QPackageRegistry::getInstance ()   [static]

Return a singleton instance of the QPackageRegistry object for this process.

void QPackageRegistry::initProgramInfo ( SxeProgramInfo & pi )

Initialise an SxeProgramInfo pi which can then be used to register a sequence of same-domain binaries.

A new key and a new program id is created and stored in pi. The other fields are unchanged.

The keyfile.sequence file is used to track and issue new program id numbers.

bool QPackageRegistry::isInstalledProgram ( QTransportAuth::Data & connectionData )

This function is deprecated.

Return true if the connectionData connection is from an installed program, ie not one which is part of the base software.

The program is installed software if it is installed in Qtopia::packagePath()

void QPackageRegistry::lockManifest ( bool & success )   [slot]

Obtain a Qtopia::lockFile() on the manifest file. This represents locking the QPackageRegistry database system to allow write operations to be done by this process.

If successfully locked, the method sets success to true; otherwise it sets it to false.

Call this method to obtain the lock before performing any write operations to the SXE database system.

This should be matched by a call to unlockManifest()

See also unlockManifest().

void QPackageRegistry::registerBinary ( SxeProgramInfo & pi )   [slot]

Register a qtopia binary with the SXE system. The path to the binary is:

pi.absolutePath()

where the SxeProgramInfo pi contains all the information about the binary.

Note that binaries with the same domain (SXE policy profile) and binaries from the same package are coalesced into the same Program Id, and thus use the same secret key.

The SxeProgramInfo pi if uninitialised is modified by creating a new random key and program id. The id and key fields if initialised are used to register the binary.

See also SxeProgramInfo.

QString QPackageRegistry::sxeConfPath () const   [virtual]

Return the authoritative path for where the SXE database files, such as installs, and manifest, are stored.

The directory must be writeable.

Current implementation is simply Qtopia::qtopiaDir() + "etc"

void QPackageRegistry::unlockManifest ()   [slot]

Release the lock on the manifest file.

See also lockManifest().

bool QPackageRegistry::unregisterPackageBinaries ( const QString & packagePath )

Unregisters a package's binaries from the SXE system for the given packagePath

returns true if the removal of the registration was successful; otherwise returns false


Member Variable Documentation

const QString QPackageRegistry::binInstallPath

returns the QString name of the relative binary path, where SXE controlled executables are installed. Concatenate this with paths from installPaths() to find full paths which may contain binaries.

See also Qtopia::installPaths().

const QString QPackageRegistry::installsFileName

returns the QString name of the installs file, part of the SXE database

See also sxeConfPath().

const QString QPackageRegistry::manifestFileName

returns the QString name of the manifest file, part of the SXE database

See also sxeConfPath().

const QString QPackageRegistry::profilesFileName

returns the QString name of the profiles file, part of the SXE database

See also sxeConfPath().

const QString QPackageRegistry::qlLibInstallPath

returns the QString name of the relative quicklaunch binary path, where SXE controlled quicklaunched executables are installed. Concatenate this with paths from installPaths() to find full paths which may contain .so files.

See also Qtopia::installPaths().


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3