README.md 8.92 KB
Newer Older
Dominik Schürmann's avatar
Dominik Schürmann committed
1 2
# F-Droid Privileged Extension

TacoTheDank's avatar
TacoTheDank committed
3 4
This enables F-Droid to install and delete apps without needing "Unknown Sources" to be enabled (e.g. just like Google Play does).
It also enables F-Droid to install updates in the background without the user having to click "install".
Dominik Schürmann's avatar
Dominik Schürmann committed
5

TacoTheDank's avatar
TacoTheDank committed
6 7 8
When F-Droid is installed as a normal Android app, installing, updating, and removing apps can only be done by sending requests to the Android operating system.
F-Droid cannot execute these operations itself. Android shows a screen on every install/update/delete to confirm this is what the user actually wants.
This is a security feature of Android to prevent apps or websites from installing malware without user intervention.
Dominik Schürmann's avatar
Dominik Schürmann committed
9

TacoTheDank's avatar
TacoTheDank committed
10 11 12 13
F-Droid Privileged Extension grants elevated permissions to F-Droid, which allows it to do installs and uninstalls without needing user approval.
It gives only F-Droid access to its install and delete commands.
In order for F-Droid Privileged Extension to get these "privileged" powers, it must be installed as part of your system by either being flashed as an _update.zip_ or by being built into an Android device or ROM.
On Android 4 and older, it can be installed directly if you have root on your device.
Dominik Schürmann's avatar
Dominik Schürmann committed
14

15

16
## Design
Dominik Schürmann's avatar
Dominik Schürmann committed
17

TacoTheDank's avatar
TacoTheDank committed
18 19
F-Droid Privileged Extension is designed on the principals of "least privilege", so that elevated powers are only granted where they are absolutely needed, and those powers are limited as much as possible.
Therefore, the code that runs with increased powers is very small and easy to audit.  This is in contrast to how typical built-in app stores are granted all of the privileges available to a "system priv-app". 
20 21 22 23 24 25 26 27 28 29 30

Advantages of this design:

* "Unknown Sources" can remain disabled
* Can easily be built into devices and ROMs
* Reduced disk usage in the system partition
* System updates don't remove F-Droid


## How do I install it on my device?

31 32 33 34 35 36
The best way to install F-Droid Privileged Extension is to flash the
[_OTA update ZIP_](https://f-droid.org/packages/org.fdroid.fdroid.privileged.ota)
file using the standard mechanism for flashing updates to the
ROM. This requires the device have an unlocked bootloader. A custom
Recovery firmware is recommended. This is the same procedure as
flashing "gapps" after flashing a ROM onto your device.
37

TacoTheDank's avatar
TacoTheDank committed
38 39 40 41
Installing the F-Droid Privileged Extension directly from the F-Droid app requires root access and is only possible on Android versions older than 5.0.
It is not possible on Android 5.1, 6.0, and newer.
To install the extension, open the settings inside the F-Droid app, enable "Expert mode", and then enable "Privileged Extension".
It will lead you to the extension app, which will guide you through the installation process.
42 43 44

There are potential risks to rooting and unlocking your device, including:

TacoTheDank's avatar
TacoTheDank committed
45
* often requires using random, unverified software
46
* bootloader unlock often voids warranty
TacoTheDank's avatar
TacoTheDank committed
47 48
* official updates might stop working with an unlocked bootloader
* other functions may break (like Android Pay, DRM-protected content playing, camera enhancements, etc.)
49 50 51 52


## How do I build it into my ROM?

TacoTheDank's avatar
TacoTheDank committed
53 54 55 56
F-Droid Privileged Extension is designed to be built into ROMs and signed by the ROM key.
F-Droid only gets permissions via F-Droid Privileged Extension's internal key check, not via having a matching signing key or via `"signature" protectionLevel`.
This git repo includes an [Android.mk](https://gitlab.com/fdroid/privileged-extension/blob/master/app/src/main/Android.mk) so it can be directly included via `repo`.
Add `F-DroidPrivilegedExtension` to the `PRODUCT_PACKAGES` list to include it in the system image, and use a `repo` manifest like this:
57 58 59 60 61 62

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>

  <remote name="fdroid" fetch="https://gitlab.com/fdroid/" />
Chirayu Desai's avatar
Chirayu Desai committed
63
  <project path="packages/apps/F-DroidPrivilegedExtension"
64
           name="privileged-extension.git" remote="fdroid"
65
           revision="refs/tags/0.2.8" />
66 67 68 69

</manifest>
```

TacoTheDank's avatar
TacoTheDank committed
70 71
By default, F-Droid Privileged Extension trusts only the official F-Droid builds, and we recommend that https://f-droid.org/F-Droid.apk is also included in the ROM.
You can verify the binaries by using both the APK signature and the PGP key: https://f-droid.org/F-Droid.apk.asc
72 73 74 75 76 77

APK signing certificate SHA-256 fingerprint:
```
43238d512c1e5eb2d6569f4a3afbf5523418b82e0a3ed1552770abb9a9c9ccab
```

TacoTheDank's avatar
TacoTheDank committed
78
PGP signing key fingerprint:
79 80 81 82
```
37D2 C987 89D8 3119 4839  4E3E 41E7 044E 1DBA 2E89
```

TacoTheDank's avatar
TacoTheDank committed
83
More documentation can be found here:
84
https://f-droid.org/wiki/page/Release_Channels_and_Signing_Keys
Dominik Schürmann's avatar
Dominik Schürmann committed
85 86 87 88


## Direct download

89 90 91 92 93 94 95 96
F-Droid Privileged Extension needs to be flashed as an OTA update on
all Android versions since 5.0 in order to function.  The official,
signed ZIP package and PGP signature are available for download from
f-droid.org:

* https://f-droid.org/packages/org.fdroid.fdroid.privileged.ota

It is also possible to download the bare APK, though this is not the
TacoTheDank's avatar
TacoTheDank committed
97
recommended way to install it for the first time.  It is provided to
98 99 100
update the extension after the OTA update ZIP has been flashed.

* https://f-droid.org/packages/org.fdroid.fdroid.privileged
101 102 103 104 105 106


## Building with Gradle

Build a complete "update.zip" to flash to a device to install F-Droid and the Privileged Extension:

107
    ./create_ota.sh debug binaries
108 109 110

Build an "update.zip" to flash to a device to install just the Privileged Extension:

111
    ./create_ota.sh debug
112

TacoTheDank's avatar
TacoTheDank committed
113
Build the standalone APK using:
114 115

    ./gradlew assembleRelease
116 117 118 119 120 121 122

In order to have final, signed release versions that are ready for installing, a release signing key must be set up in _signing.properties_ with these contents:

    key.store=/path/to/release-keystore.jks
    key.store.password=mysecurestorepw
    key.alias=release
    key.alias.password=mysecurekeypw
123

124 125 126 127 128 129

## Supporting a different app

It is possible to use Privileged Extension with any app.  To do that,
make a "whitelabel" build of Privileged Extension that includes the
_Application ID_, key fingerprint, and app name for the app that the
TacoTheDank's avatar
TacoTheDank committed
130
custom build will support.  These are set by the script below, and
131 132 133 134 135 136 137 138 139 140 141 142 143
should be committed to a fork git repo:

```bash
$ export ApplicationID=my.app
$ export AppName=MyApp
sed -i "s,org.fdroid.fdroid.privileged,$ApplicationID,g" \
    create_ota.sh app/src/main/scripts/*
$ sed -i "s,F-Droid,$AppName,g" \
    create_ota.sh app/build.gradle app/src/main/scripts/* \
    app/src/main/res/values*/strings.xml
```


144 145
## Testing in the Emulator

TacoTheDank's avatar
TacoTheDank committed
146
To test the Privileged Extension in the emulator, one has to modify
147 148 149
the _system.img_ file. It is located under the Android SDK install
path.  For example, here is the `android-23` (Marshmallow, 6.0) x86_64
image with Google APIs:
150

151
```
152
$ANDROID_HOME/system-images/android-23/google_apis/x86_64/system.img
153 154
```

155 156 157 158
To install it, first build the standalone APK, and then run these in
the base directory of this git repo.  This copies the APK into the
right place, and sets up the correct SELinux context.

159 160
### _android-14_ through _android-25_

161 162 163 164 165 166 167 168
```console
$ ./gradlew assembleDebug
$ mkdir /tmp/system
$ sudo mount -o loop /path/to/system.img /tmp/system
$ sudo mkdir /tmp/system/priv-app/F-DroidPrivilegedExtension
$ sudo cp app/build/outputs/apk/F-DroidPrivilegedExtension-debug.apk \
    /tmp/system/priv-app/F-DroidPrivilegedExtension/F-DroidPrivilegedExtension.apk
$ sudo chcon -R --reference=/tmp/system/app/webview /tmp/system/priv-app/F-DroidPrivilegedExtension
169 170 171 172 173 174
$ sudo umount /tmp/system
```

### _android-26_ and newer

Starting with _android-26_, the _system.img_ files have a different
TacoTheDank's avatar
TacoTheDank committed
175 176
format that needs to be unpacked before it can be mounted.  It
has to be repacked after mounting as well.  This requires the _simg2img_ and
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
_make_ext4fs_ utilities.

```console
$ sudo apt-get install android-tools-fsutils
$ ./gradlew assembleDebug
$ simg2img /path/to/system.img system.img.raw
$ mkdir /tmp/system
$ sudo mount -t ext4 -o loop system.img.raw /tmp/system
$ sudo mkdir /tmp/system/priv-app/F-DroidPrivilegedExtension
$ sudo cp app/build/outputs/apk/F-DroidPrivilegedExtension-debug.apk \
    /tmp/system/priv-app/F-DroidPrivilegedExtension/F-DroidPrivilegedExtension.apk
$ sudo chcon -R --reference=/tmp/system/app/webview /tmp/system/priv-app/F-DroidPrivilegedExtension
$ make_ext4fs -s -T -1 -S file_contexts -L system -l 512M -a system system.img.new /tmp/system
$ sudo umount /tmp/system
$ mv system.img.new /path/to/system.img
192
```
193

TacoTheDank's avatar
TacoTheDank committed
194
Upon booting the emulator, it should have the Privileged Extension
195 196
installed.  It is also possible to install the F-Droid app this way,
or via the normal methods.
197 198 199 200 201 202


## via _adb_ on _android-19_ and older

On old Android versions (4.4 and older), it is possible using only
_adb_, but then each time the emulator is rebooted, it will lose the
TacoTheDank's avatar
TacoTheDank committed
203
changes.  Take a snapshot after completing this process to save the
204 205 206 207 208 209 210 211 212 213
state.

```console
$ adb -e root
$ adb -e remount
$ adb -e shell mkdir /system/priv-app/F-DroidPrivilegedExtension
$ sudo cp app/build/outputs/apk/F-DroidPrivilegedExtension-debug.apk \
    /tmp/system/priv-app/F-DroidPrivilegedExtension/F-DroidPrivilegedExtension.apk
$ sudo chcon -R --reference=/tmp/system/app/webview /tmp/system/priv-app/F-DroidPrivilegedExtension
```