SWIPOLICY.INI

Parameter

Description

AllowUnsigned=[true | false]

This flag determines whether or not the installation of unsigned packages is allowed.

If true, unsigned packages are considered as candidates for installation. If false, the Software Installer refuses to install unsigned packages.

Notes:

• If there is a root certificate marked as MANDATORY in the SWI certificate store, then even if AllowUnsigned is set to true, the installation will fail unless the package is signed with a verifiable end entity certificate.

• If any of the executables in an unsigned package have system capabilities then the installation is aborted with an error message, even if unsigned packages are allowed.

The default is false.

MandateCodeSigningExtension=[true | false]

This flag may be used to force end entity certificates to have the X.509 codesigning extension (see RFC 3280).

If true, all end entity certificates corresponding to the private keys used to sign the SIS files being installed must have either the standard X.509 codesigning OID (1.3.6.1.5.5.7.3.3), or an alternative OID specified using AlternativeCodeSigningOID, described later in this document. If the certificate does not have either of these extensions, the package will not be installed.

If false, the code signing extension is not required.

The default is false.

MandatePolicies=[true | false]

This flag may be used to force all non-root certificates in chains corresponding to the private keys used to sign the SIS file to contain at least one of the OIDs specified in the policy file. If not, the package will not be installed (ECertificateValidationError will be generated). The certificates must be signed with the X.509 extended key usage extension that contains one of the specified OIDs.

If true, all the certificates (except the root) in the chains corresponding to the private keys used to sign the SIS file must contain one of the OIDs defined in the policy file.

If false, the absence or presence of the OID does not affect the installation.

For example, if it is a requirement that certificates must contain the OID 1.2.826.0.1.1796587.1, then MandatePolicies should be set to true and 1.2.826.0.1.1796587.1 should appear in the list of Oids. Also, if OpenSSL, for example, is used to sign the certificates then the corresponding configuration file would contain lines such as:

[ Signing_Extensions ]           
extendedKeyUsage=codeSigning,1.2.826.0.1.1796587.1

The default is false.

Oid = value

A list of OIDs, one of which must be present in each of the certificates if the MandatePolicies setting is set to true.

DRMEnabled =[true | false]

A boolean flag to indicate whether the installation process should allow the installation of DRM protected SIS files.

If true, the Software Installer will ensure that the correct rights are available for the DRM protected content before carrying out the installation. The rights will be executed at the end of the installation. The Software Installer ensures that the installation will never complete without executing the rights, and conversely that the rights shall never be executed without finishing the installation.

It is expected that rights will already be available on the device. Where no rights are available, the installation will fail.

If false, the Software Installer will not attempt to do any DRM processing on the provided files and installation of DRM protected files will fail.

The default is true.

DRMIntent = value

If the DRMEnabled setting is set to true, the DRMIntent setting indicates the intent that should be used by the Software Installer for the evaluation and execution of rights when installing the SIS file. Symbian cannot determine which intent a licensee will wish to apply to the installation process; hence this setting has to be configurable.

If DRMEnabled is set to false then the DRMIntent setting is ignored.

The value can be one of:

• 0 Indicates the intent is to peek at content. Peek implies that no DRM operation involving rights is performed i.e. that the installer is outside the DRM activation context.

• 1 Indicates the intent is to play content.

• 2 Indicates the intent is to view content.

• 3 Indicates the intent is to execute content.

• 4 Indicates the intent is to print content.

• 5 Indicates the intent is to pause the play operation.

• 6 Indicates the intent is to continue to play content after a pause operation.

• 7 Indicates the intent is to stop the playing of content.

• 8 Indicates uncertainty about how the content will be used. It permits free access to unprotected data but prevents access to protected content.

• 9 Indicates the intent is to install content. This value is provided to allow a licensee to register the installation as a DRM operation.

The default value is 3.

OcspEnabled = [true | false]

This flag determines whether OCSP checking is performed during software installation.

If true, OCSP is enabled and the Software Installer may carry out an OCSP check during the installation. If false, OCSP checking is not performed.

A SIS file can be signed with multiple certificates. If enabled, OCSP checking verifies the current status of the certificates in all chains built from the SIS file. All chains present are checked and must prove valid.

Note that failure of the OCSP check does not necessarily cause installation to fail. Transient errors in verification (for example due to network problems) may be permitted, depending upon the OcspMandatory setting.

If OCSP indicates that any of the certificates have been revoked, or if the signature on the OCSP response is invalid, a security error will be issued and the software cannot be installed.

The OCSP server URI is taken from the corresponding certificate (as long as the chain is trusted). If there is no OCSP server URI specified in a certificate, a default URI is used that is taken from the installation preferences passed to the Software Installer.

OCSP responses are considered valid when signed either by a CA that is part of the chain used to validate the SIS file signature or by a root certificate that is installed on the device and explicitly marked as trusted for revocation purposes.

The default is false.

OcspMandatory = [true | false]

If OcspEnabled is set to true then this setting determines whether the outcome of the OCSP check must be successful or not before installation can be carried out.

If true, OCSP checking must succeed in order to install the package. If there is only one chain built from the SIS file, and OcspMandatory is true, then errors during the OCSP check cause the package to be considered unknown and to be handled in the same way as an unsigned SIS file.

If false, a transient problem with OCSP checking will not halt the installation process.

The default is false.

AllowGrantUserCapabilities = [true | false]

This flag determines whether the user can grant user capabilities (as defined by the UserCapabilites setting) to executables at install time. If not, user capabilities must be endorsed by a trust anchor certificate on the device.

If true, users are allowed to grant user capabilities.

If false, users are not allowed to grant user capabilities, the list of capabilities specified in UserCapabilites is ignored and all capability endorsements must come from the certificate chains.

The default is false.

UserCapabilities = capability1.. capabilityN

This specifies the list of the capabilities that the user can grant to an executable during the installation of a package if the AllowGrantUserCapabilities policy is set to true.

User capabilities are the set of capabilities whose purpose may be easily understood by a user. The rules governing the installation of a software package containing executables vary depending on whether the executables require user or system capabilities.

If a package requires any system capabilities then these capabilities must be endorsed by an appropriate certificate, or installation will fail. In other words, a trust anchor certificate, X, that can grant all capabilities required by the package’s executables must be present in the SWI Certificate Store and the package must be signed with a verifiable EE certificate derived from X.

Trust anchor certificates may also endorse user capabilities. Any packages requesting those capabilities and signed with a verifiable EE certificate will also be considered for installation without querying the user. However, if the package requests user capabilities but it is not signed with such a certificate, and if the AllowGrantUserCapabilities policy is set to true, the user will be asked if they wish to grant the capabilities to the package.

The standard set of user capabilities is:

• NetworkServices

  Grants access to remote services without any restriction on its physical location i.e. grants access to the phone network. An application that has been given this capability can dial a number, send a text message etc. and thus may incur a cost for the phone user.

• LocalServices

  Grants access to remote services in the close vicinity of the phone i.e. grants access to the local network. An application with this capability can send or receive information through Bluetooth, USB or IR. In most cases such services will not incur a cost for the phone user.

• UserEnvironment

  Grants access to live confidential information about the user and his/her immediate environment. Examples are biometric data (such as blood pressure), audio and video recording.

• ReadUserData

  Grants read access to user data, such as contacts, messaging and calendar data.

• WriteUserData

  Grants write access to user data.

• Location

  Grants access to the live location of the device. This capability supports the management of the user’s privacy regarding the phone location. Location information protected by this capability can include map co-ordinates and street address, but not regional or national scale information.

Note that defining a set of user capabilities in swipolicy.ini that differs from the 'standard' set as agreed with an operator or with a signing programme such as Symbian Signed may cause problems for end users.

DRM capability cannot be granted to users. Because TCB applications can escalate privileges to gain DRM, TCB capability also cannot be granted to users. Even if either DRM or TCB are granted to users in SWI policy INI files, they won't be granted to users by the software installer.

AllowOrphanedOverwrite = [true | false]

This flag determines whether the user is asked to allow the overwriting of orphaned files in public directories during the installation. A file is considered orphaned if it does not belong to any installed package in the registry. This could be a newly created file or a Symbian OS file not referenced in a ROM stub controller. To allow the overwriting of files in private directories, the AllowProtectedOrphanOverwrite flag must additionally be set to true.

Because orphans could potentially be used to block legitimate packages from being installed, the Software Installer allows them to be overwritten if they are 'in the way', but only if the user allows this to happen.

If true, orphaned files can be overwritten during the installation of a package.

If false, orphaned files are not overwritten.

The default is false.

AllowProtectedOrphanOverwrite = [true | false]

If true, (and if AllowOrphanedOverwrite is also true) the Software Installer will allow orphaned files located in private directories (/private/xxxxxxxx/import, /resource or /sys/bin) to be overwritten or eclipsed (with user permission). Note that this flag only allows the overwriting of files in private directories to which the package has permission to write.

The default is true.

AllowPackagePropagate = [true | false]

When a software package (of type SA or SP) is wholly installed onto a removable media card and if AllowPackagePropagate is set to true, the Software Installer will write a stub SIS file to the /private/10202DCE directory of that media card.

A stub SIS file is one which contains no data units i.e. files or executables. Appending the stub SIS file to a card allows the card to be inserted into another device and the package will be automatically installed.

This means that if AllowPackagePropagate is set to true then a user can install a package to a media card, give the card to another user and the package will automatically install on their device. If it is set to false then a stub SIS file is not created on the media card so the application will only work when the card is in the original device.

The default is false.

ApplicationShutdownTimeoutSeconds = value

This specifies the maximum allowed shutdown time in seconds for applications that are required to be shut down during an upgrade or uninstall operation. If the application fails to shut down within this time, the Software Installer shuts it down by killing the process.

The default value is 10 seconds.

RunWaitTimeoutSeconds = value

An installation package can specify that a program will run during the installation process (specified using FILERUN or FILEMIME in the PKG file). Additionally, the RUNWAITEND flag can be specified. If RUNWAITEND is not specified, the default behaviour is to run the program and continue with the (un)installation. The program is shut down when the (un)installation is complete. Specifying RUNWAITEND causes the Software Installer to wait a period of time for the program to terminate before continuing with the installation. That period of time is specified by the RunWaitTimeoutSeconds value. If the program fails to shut down within this time, the Software Installer shuts it down by killing the process.

Users of these features should be aware of the following:

• If the Software Installer is configured with a positive RunWaitendTimeoutSeconds value, installation will continue after this time if the executable has not exited of its own accord.

• With a RunWaitTimeoutSeconds value of -1, the Software Installer will wait indefinitely for the executable to terminate. If the executable never exits, the Software Installer will hang forever.

• Launching a UI application with this mechanism is not recommended because its windows may interact unpredictably with those of the installer UI, or user delay may result in installation/uninstallation continuing regardless. FILERUN and FILEMIME are intended for launching background processes with no UI.

• Using FILERUN or FILEMIME to launch executables in the package that use resource files is also not recommended because AppArc may only complete resource file registration after (un)installation has fully completed.

The default value is 3 minutes.

SISCompatibleIfNoTargetDevices = [true | false]

This flag determines whether SIS files with no target hardware/UI platform dependencies listed are considered compatible with any target hardware.

If true, an installation package with no hardware/UI platform dependency statement is considered compatible with all target hardware/UI platforms.

If false, such a package will be treated in the same way as SIS files with target devices listed but which do not match any UIDs in the Software Installer registry, i.e. the Installer instructs the UI using a callback (MInstallerUiHandler::DisplayMissingDependencyL()) to inform the user about the missing dependency.

The default is true.

AllowRunOnInstallUninstall = [true | false]

This flag determines whether untrusted applications are allowed to execute via the FILERUN (FR) or FILEMIME (FM) directives.

Note: these directives are not supported for use with PA media types.

The default is true.

ReplacePath = searchPath|replacePath1|...|replacePathN|

This setting allows a device manufacturer to remap the location to which files are installed on the device at install (or restore) time. The syntax is:

ReplacePath = <search-path>|<replace-path-1>|<...>|<replace-path-n>|

Where <search-path> is a pathname without the drive letter and colon, but with a trailing backslash. This must target the left-hand-side (LHS) of a file path (otherwise a match will not be made).

<replace-path-n> contains a lower case drive letter followed by a colon and the replacement path. The path must have a trailing backslash and be followed by a vertical bar. The last replacement path must also be followed by a vertical bar. In debug builds the parsing code in CSecurityPolicy asserts the formatting is correct.

For example:

ReplacePath = \REPLACE1\|c:\_REPLACE1C\|x:\_REPLACE1X\|$:\_REPLACE1$\|

which will cause the following remapping:

• C:\REPLACE1\ will translate to C:\_REPLACE1C\

• X:\REPLACE1\ will translate to X:\_REPLACE1X\

• $:\REPLACE1\ will be translated accordingly. For instance, if C: is the system drive, there are 2 possible translations: c:\_REPLACE1C\ and C:\_REPLACE1$\. In this case, c:\_REPLACE1C\ will be used because it occurs first in the list.

• D:\REPLACE1\ will not be translated since there is no replacement string specified (unless D: is the system drive, in which case, it would be translated as D:\_REPLACE1$\).

• !:\REPLACE1\ will be translated accordingly, but only if the user selects install drive C or X.

• C:\REPLACE1\ANOTHER\ will translate to C:\_REPLACE1C\ANOTHER\.

Important Note: ReplacePath only supports the translation of ASCII file-paths. Support for Unicode translation is not currently supported.

OcspHttpHeaderFilter = value

This specifies a filter that adds HTTP headers to OCSP requests. A filter is an ECOM plugin.

This setting is optional. If none is specified then the OCSP request is sent with the default headers. These are POST method, Close header and application/ocsp-request Content Type. The Host header and Content-Length are added by the HTTP module.

The value is the UID of the plugin in hex. For example,

OcspHttpHeaderFilter = 10200A8A

DeletePreinstalledFilesOnUninstall = [true | false]

If true, the Software Installer will attempt to remove all pre-installed files on a writable MMC card when a package is uninstalled. All related private directories on all drives will also be removed. Removal is suppressed if the PA (or PP) stub SIS file is read-only in the file system. If the card is not present when the uninstall occurs, the files will be removed from the card the next time it is inserted into the phone.

If false (the default behaviour) the registry entry for the package is removed but the pre-installed files (and private directories) are left untouched, so no files are removed.

Note that configuring this option means that if one user lends an MMC card to another, nothing prevents the second user from inadvertently removing the package from the MMC.

The default is false.

RemoveOnlyWithLastDependent = [true | false]

If true, when uninstalling a package which embeds another package, the embedded package is not removed if a third package is dependent on it. If false, the embedded package is removed along with the embedding package, even if another package depends on it.

For example, in the diagram below, package A and package C both embed and depend on package B. If RemoveOnlyWithLastDependent is true, uninstalling package C does not cause B to be uninstalled because A still depends on it. If RemoveOnlyWithLastDependent is false, uninstalling package C does cause B to be uninstalled even though A still depends on it.

The default is false.

PhoneTsyName = value

Provides the phone's TSY name to the software installer. This is required when restoring applications that have been signed using a developer certificate with an IMEI constraint. The software installer requires the TSY name in order to retrieve the phone's IMEI number.

The default is an empty string. In other words, by default, applications that are signed using a developer certificate with an IMEI constraint are not restored.

AlternativeCodeSigningOID = value

Specifies an alternative codesigning OID to the standard X.509 codesigning OID (1.3.6.1.5.5.7.3.3).

Certificate validation will fail in the following situations:

• if the X.509 extended key usage OID (2.5.29.37) is present in the certificate but neither the standard X.509 codesigning OID (1.3.6.1.5.5.7.3.3) nor the alternative codesigning OID (specified by AlternativeCodeSigningOID) is also present,

• if the extended key usage OID is absent from the certificate but codesigning is mandated in swipolicy.ini (via the MandateCodeSigningExtension setting).