{"id":18511699,"url":"https://github.com/f-droid/privileged-extension","last_synced_at":"2025-04-14T07:06:14.789Z","repository":{"id":65546726,"uuid":"205026605","full_name":"f-droid/privileged-extension","owner":"f-droid","description":"mirror of https://gitlab.com/fdroid/privileged-extension/","archived":false,"fork":false,"pushed_at":"2024-07-09T17:48:57.000Z","size":426,"stargazers_count":60,"open_issues_count":0,"forks_count":17,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-14T07:05:24.537Z","etag":null,"topics":["android","android-application","fdroid"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/f-droid.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"liberapay":"F-Droid-Data","open_collective":"F-Droid","github":["f-droid"],"custom":["https://f-droid.org/donate/","https://www.hellotux.com/f-droid"]}},"created_at":"2019-08-28T21:29:10.000Z","updated_at":"2025-04-07T20:12:01.000Z","dependencies_parsed_at":"2024-12-31T17:30:55.742Z","dependency_job_id":"91ea14ef-26ba-4480-b646-e09135438abb","html_url":"https://github.com/f-droid/privileged-extension","commit_stats":{"total_commits":228,"total_committers":85,"mean_commits":"2.6823529411764704","dds":0.5877192982456141,"last_synced_commit":"3a2b951f7470e99444d5c1840764bf86b7b0a2a1"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f-droid%2Fprivileged-extension","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f-droid%2Fprivileged-extension/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f-droid%2Fprivileged-extension/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f-droid%2Fprivileged-extension/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f-droid","download_url":"https://codeload.github.com/f-droid/privileged-extension/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837281,"owners_count":21169374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-application","fdroid"],"created_at":"2024-11-06T15:29:28.444Z","updated_at":"2025-04-14T07:06:14.727Z","avatar_url":"https://github.com/f-droid.png","language":"Java","funding_links":["https://liberapay.com/F-Droid-Data","https://opencollective.com/F-Droid","https://github.com/sponsors/f-droid","https://f-droid.org/donate/","https://www.hellotux.com/f-droid"],"categories":[],"sub_categories":[],"readme":"# F-Droid Privileged Extension\n\nThis enables F-Droid to install and delete apps without needing \"Unknown Sources\" to be enabled (e.g. just like Google Play does).\nIt also enables F-Droid to install updates in the background without the user having to click \"install\".\n\nWhen 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.\nF-Droid cannot execute these operations itself. Android shows a screen on every install/update/delete to confirm this is what the user actually wants.\nThis is a security feature of Android to prevent apps or websites from installing malware without user intervention.\n\nF-Droid Privileged Extension grants elevated permissions to F-Droid, which allows it to do installs and uninstalls without needing user approval.\nIt gives only F-Droid access to its install and delete commands.\nIn 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.\nOn Android 4 and older, it can be installed directly if you have root on your device.\n\n\n## Design\n\nF-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.\nTherefore, 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\". \n\nAdvantages of this design:\n\n* \"Unknown Sources\" can remain disabled\n* Can easily be built into devices and ROMs\n* Reduced disk usage in the system partition\n* System updates don't remove F-Droid\n\n\n## How do I install it on my device?\n\nThe best way to install F-Droid Privileged Extension is to flash the\n[_OTA update ZIP_](https://f-droid.org/packages/org.fdroid.fdroid.privileged.ota)\nfile using the standard mechanism for flashing updates to the\nROM. This requires the device have an unlocked bootloader. A custom\nRecovery firmware is recommended. This is the same procedure as\nflashing \"gapps\" after flashing a ROM onto your device.\n\nInstalling 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.\nIt is not possible on Android 5.1, 6.0, and newer.\nTo install the extension, open the settings inside the F-Droid app, enable \"Expert mode\", and then enable \"Privileged Extension\".\nIt will lead you to the extension app, which will guide you through the installation process.\n\nThere are potential risks to rooting and unlocking your device, including:\n\n* often requires using random, unverified software\n* bootloader unlock often voids warranty\n* official updates might stop working with an unlocked bootloader\n* other functions may break (like Android Pay, DRM-protected content playing, camera enhancements, etc.)\n\n\n## How do I build it into my ROM?\n\nF-Droid Privileged Extension is designed to be built into ROMs and signed by the ROM key.\nF-Droid only gets permissions via F-Droid Privileged Extension's internal key check, not via having a matching signing key or via `\"signature\" protectionLevel`.\nThis 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`.\nAdd `F-DroidPrivilegedExtension` to the `PRODUCT_PACKAGES` list to include it in the system image, and use a `repo` manifest like this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cmanifest\u003e\n\n  \u003cremote name=\"fdroid\" fetch=\"https://gitlab.com/fdroid/\" /\u003e\n  \u003cproject path=\"packages/apps/F-DroidPrivilegedExtension\"\n           name=\"privileged-extension.git\" remote=\"fdroid\"\n           revision=\"refs/tags/0.2.13\" /\u003e\n\n\u003c/manifest\u003e\n```\n\nBy 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.\nYou can verify the binaries by using both the APK signature and the PGP key: https://f-droid.org/F-Droid.apk.asc\n\nAPK signing certificate SHA-256 fingerprint:\n```\n43238d512c1e5eb2d6569f4a3afbf5523418b82e0a3ed1552770abb9a9c9ccab\n```\n\nPGP signing key fingerprint:\n```\n37D2 C987 89D8 3119 4839  4E3E 41E7 044E 1DBA 2E89\n```\n\nMore documentation can be found here:\nhttps://f-droid.org/wiki/page/Release_Channels_and_Signing_Keys\n\n\n## Direct download\n\nF-Droid Privileged Extension needs to be flashed as an OTA update on\nall Android versions since 5.0 in order to function.  The official,\nsigned ZIP package and PGP signature are available for download from\nf-droid.org:\n\n* https://f-droid.org/packages/org.fdroid.fdroid.privileged.ota\n\nIt is also possible to download the bare APK, though this is not the\nrecommended way to install it for the first time.  It is provided to\nupdate the extension after the OTA update ZIP has been flashed.\n\n* https://f-droid.org/packages/org.fdroid.fdroid.privileged\n\n\n## Building with Gradle\n\nBuild a complete \"update.zip\" to flash to a device to install F-Droid and the Privileged Extension:\n\n    ./create_ota.sh debug binaries\n\nBuild an \"update.zip\" to flash to a device to install just the Privileged Extension:\n\n    ./create_ota.sh debug\n\nBuild the standalone APK using:\n\n    ./gradlew assembleRelease\n\nIn 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:\n\n    key.store=/path/to/release-keystore.jks\n    key.store.password=mysecurestorepw\n    key.alias=release\n    key.alias.password=mysecurekeypw\n\n\n## Supporting a different app\n\nIt is possible to use Privileged Extension with any app.  To do that,\nmake a \"whitelabel\" build of Privileged Extension that includes the\n_Application ID_, key fingerprint, and app name for the app that the\ncustom build will support.  These are set by the script below, and\nshould be committed to a fork git repo:\n\n```bash\n$ export ApplicationID=my.app\n$ export AppName=MyApp\nsed -i \"s,org.fdroid.fdroid.privileged,$ApplicationID,g\" \\\n    create_ota.sh app/src/main/scripts/*\n$ sed -i \"s,F-Droid,$AppName,g\" \\\n    create_ota.sh app/build.gradle app/src/main/scripts/* \\\n    app/src/main/res/values*/strings.xml\n```\n\n\n## Testing in the Emulator\n\nTo test the Privileged Extension in the emulator, one has to modify\nthe _system.img_ file. It is located under the Android SDK install\npath.  For example, here is the `android-23` (Marshmallow, 6.0) x86_64\nimage with Google APIs:\n\n```\n$ANDROID_HOME/system-images/android-23/google_apis/x86_64/system.img\n```\n\nTo install it, first build the standalone APK, and then run these in\nthe base directory of this git repo.  This copies the APK into the\nright place, and sets up the correct SELinux context.\n\n### _android-14_ through _android-25_\n\n```console\n$ ./gradlew assembleDebug\n$ mkdir /tmp/system\n$ sudo mount -o loop /path/to/system.img /tmp/system\n$ sudo mkdir /tmp/system/priv-app/F-DroidPrivilegedExtension\n$ sudo cp app/build/outputs/apk/F-DroidPrivilegedExtension-debug.apk \\\n    /tmp/system/priv-app/F-DroidPrivilegedExtension/F-DroidPrivilegedExtension.apk\n$ sudo chcon -R --reference=/tmp/system/app/webview /tmp/system/priv-app/F-DroidPrivilegedExtension\n$ sudo umount /tmp/system\n```\n\n### _android-26_ and newer\n\nStarting with _android-26_, the _system.img_ files have a different\nformat that needs to be unpacked before it can be mounted.  It\nhas to be repacked after mounting as well.  This requires the _simg2img_ and\n_make_ext4fs_ utilities.\n\n```console\n$ sudo apt-get install android-tools-fsutils\n$ ./gradlew assembleDebug\n$ simg2img /path/to/system.img system.img.raw\n$ mkdir /tmp/system\n$ sudo mount -t ext4 -o loop system.img.raw /tmp/system\n$ sudo mkdir /tmp/system/priv-app/F-DroidPrivilegedExtension\n$ sudo cp app/build/outputs/apk/F-DroidPrivilegedExtension-debug.apk \\\n    /tmp/system/priv-app/F-DroidPrivilegedExtension/F-DroidPrivilegedExtension.apk\n$ sudo chcon -R --reference=/tmp/system/app/webview /tmp/system/priv-app/F-DroidPrivilegedExtension\n$ make_ext4fs -s -T -1 -S file_contexts -L system -l 512M -a system system.img.new /tmp/system\n$ sudo umount /tmp/system\n$ mv system.img.new /path/to/system.img\n```\n\nUpon booting the emulator, it should have the Privileged Extension\ninstalled.  It is also possible to install the F-Droid app this way,\nor via the normal methods.\n\n\n## via _adb_ on _android-19_ and older\n\nOn old Android versions (4.4 and older), it is possible using only\n_adb_, but then each time the emulator is rebooted, it will lose the\nchanges.  Take a snapshot after completing this process to save the\nstate.\n\n```console\n$ adb -e root\n$ adb -e remount\n$ adb -e shell mkdir /system/priv-app/F-DroidPrivilegedExtension\n$ sudo cp app/build/outputs/apk/F-DroidPrivilegedExtension-debug.apk \\\n    /tmp/system/priv-app/F-DroidPrivilegedExtension/F-DroidPrivilegedExtension.apk\n$ sudo chcon -R --reference=/tmp/system/app/webview /tmp/system/priv-app/F-DroidPrivilegedExtension\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff-droid%2Fprivileged-extension","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff-droid%2Fprivileged-extension","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff-droid%2Fprivileged-extension/lists"}