Sailfish OS application sandboxing and permissions system is build on top of Firejail. The Firejail documentation can be found from here.

The Sailfish OS application permissions are applicable only to sandboxed applications. Target is to have application sandboxing enforced to all applications but currently we are not there yet. Note that permission system is only available for 1st and 2nd party application developers.

Application launch happens via standard desktop file that has been augmented so that it contains necessary metadata (such as a list of requested permissions) and Sailjail launcher is used to execute the application binary.

Permissions that an application can request are defined in this package, in terms of files containing standard Firejail directives and Sailfish OS specific metadata.

There are few changes needed for an application in order to run it in a sandbox.

Let's go through needed changes via an example.

[Desktop Entry]
Type=Application
Name=MyApplication
Icon=my-app-icon
Exec=/usr/bin/sailjail -p org.foobar.myapp.desktop /usr/bin/org.foobar.myapp
[X-Sailjail]
Permissions=Internet;Pictures
OrganizationName=org.foobar
ApplicationName=myapp

For Exec line use sailjail to start the application, pass the file name of the desktop file, and refer to the application binary with the full path.

To declare permissions and data directories you need to add X-Sailjail section to the desktop file. Under the X-Sailjail section add

Permissions are listed later in the document. They grant access to certain data paths, D-Bus interfaces, socket types and application binaries. Currently applications must define all needed permissions in desktop file and all of them are granted at launch.

OrganizationName and ApplicationName is used for granting for the application write access to

1. $HOME/.local/share/<OrganizationName>/<ApplicationName>
2. $HOME/.cache/<OrganizationName>/<ApplicationName>
3. $HOME/.config/<OrganizationName>/<ApplicationName>

Access above directories from the application through QStandardPaths

1. Application data location - QStandardPaths::writableLocation(QStandardPaths::AppDataLocation)
2. Application cache location - QStandardPaths::writableLocation(QStandardPaths::CacheLocation)
3. Application config location - QStandardPaths::writableLocation(QStandardPaths::ConfigLocation)

Only these directories can be used for storing application specific data that needs to persist over application restarts.

Modify Qt application main function by setting the organization and application name to match the declaration added to the desktop file.

QScopedPointer<QGuiApplication> app(Sailfish::createApplication(argc, argv));
...
app->setOrganizationName(QStringLiteral("org.foobar"));
app->setApplicationName(QStringLiteral("myapp"));
...

When Sailfish App library (libsailfishapp) is used these values are set automatically to the values set in desktop file.

Directories under user home such as Documents, Downloads, Music, Pictures and Videos contain files that are available for applications with respective permissions. Those directories must be used when the data needs to be accessible by other applications.

If application doesn't have a permission for a directory, all data in that directory will be hidden and the application sees only an empty read-only directory in that path. This allows to regular file access checks to function in expected way.

Permissions that applications may use (names are subject to change):

Internal permissions that applications generally should not use directly:

The metadata is used to generate translations build time and to display useful information on UI about the permissions.

Permission files have metadata in their comments. Each metadata line begins with comment character '#' and key that begins with x-sailjail- followed by '=' character and the value. Below you can find the keys that permissions should define.