1 ## Why another Superuser?
2 * Superuser should be open source. It's the gateway to root on your device. It must be open for independent security analysis. Obscurity (closed source) is not security.
3 * Superuser should be NDK buildable. No internal Android references.
4 * Superuser should also be AOSP buildable for those that want to embed it in their ROM.
5 * Superuser should also be AOSP _embeddable_, meaning a ROM can easily embed it into their Settings app.
6 * Maintenance and updates on both the market and source repositories should be timely.
7 * I want to be able to point users of my app to a Superuser solution that I wrote, that I know works, and that I can fix if something is wrong. Yes, this is selfish: Carbon does not work with some versions of Chainsdd's Superuser. SuperSU works great, but I am not comfortable pointing a user to a closed source su implementation.
8 * Handle multiuser (4.2+) properly
9 * Handle concurrent su requests properly
11 ## Checking out the source
13 You'll need the "Widgets" dependency.
15 * $ mkdir /path/to/src
17 * $ git clone git://github.com/koush/Superuser
18 * $ git clone git://github.com/koush/Widgets
20 These repositories do not keep the actual projects in the top level directory.
21 This is because they contain tests, libs, and samples.
25 In Eclipse, import Widgets/Widgets and Superuser/Superuser. It should Just Work (TM).
29 * $ mkdir /path/to/src
31 * $ cd Superuser/Superuser
33 In this directory, create a file called local.properties. This file is used by ant for custom properties. You need to specify the location of the ndk directory:
36 ndk.dir=/Users/koush/src/android-ndk
44 * bin/update.zip - Recovery installable zip
45 * bin/Superuser.apk - Superuser Android app
46 * libs/armeabi/su - ARM su binary
47 * libs/x86/su - x86 su binary
49 ## Building the su binary
51 You can use ant as shown above, to build the binary, but it can also be built without building the APK.
52 Make sure you have the android-ndk downloaded with the tool "ndk-build" in your path.
55 * $ cd Superuser/Superuser
58 The su binary will built into Superuser/Superuser/libs/armeabi/su.
62 ## Building with AOSP, CyanogenMod, etc
64 ROM developers are welcome to distribute the official Superuser APK and binary that I publish. That will
65 allow them to receive updates with Google Play. However, you can also build Superuser as part of your
66 build, if you choose to.
68 There are two ways to include Superuser in your build. The easiest is to build the APK as a separate app.
69 To do that, simply add the local_manifest.xml as described below. The second way is by embedding it
70 into the native Android System Settings.
73 Add the [local_manifest.xml](https://github.com/koush/Superuser/blob/master/local_manifest.xml) to your .repo/local_manifests
75 #### Configuring the Package Name
76 The Superuser distributed on Google Play is in the package name com.koushikdutta.superuser.
77 To prevent conflicts with the Play store version, the build process changes the package
78 name to com.thirdparty.superuser. You can configure this value by setting the following
79 in your vendor makefile or BoardConfig:
82 SUPERUSER_PACKAGE := com.mypackagename.superuser
85 #### Advanced - Embedding Superuser into System Settings
87 You will not need to change the package name as described above. Superuser will simply go
88 into the com.android.settings package.
90 First, in a product makefile (like vendor/cm/config/common.mk), specify the following:
93 SUPERUSER_EMBEDDED := true
96 To modify the Settings app, you will need this [patch](http://review.cyanogenmod.org/#/c/32957/).
97 The patch simply references the sources checked out to external/koush and makes changes
98 to XML preference files and the AndroidManifest.xml. It is a very minimal change:
102 diff --git a/Android.mk b/Android.mk
103 index fe8ed2d..6dea5b0 100644
106 @@ -13,6 +13,11 @@ LOCAL_CERTIFICATE := platform
108 LOCAL_PROGUARD_FLAG_FILES := proguard.flags
110 +LOCAL_AAPT_INCLUDE_ALL_RESOURCES := true
111 +LOCAL_AAPT_FLAGS := --extra-packages com.koushikdutta.superuser:com.koushikdutta.widgets -S $(LOCAL_PATH)/../../../external/koush/Widgets/Widgets/res -S $(LOCAL_PATH)/../../../external/koush/Superuser/Superuser/res --auto-add-overlay
113 +LOCAL_SRC_FILES += $(call all-java-files-under,../../../external/koush/Superuser/Superuser/src) $(call all-java-files-under,../../../external/koush/Widgets/Widgets/src)
115 include $(BUILD_PACKAGE)
117 # Use the folloing include to make our test apk.
118 diff --git a/AndroidManifest.xml b/AndroidManifest.xml
119 index 72be71b..4171800 100644
120 --- a/AndroidManifest.xml
121 +++ b/AndroidManifest.xml
123 <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
124 <uses-permission android:name="android.permission.SET_TIME" />
127 + android:name="android.permission.REQUEST_SUPERUSER"
128 + android:protectionLevel="signature" />
130 + android:name="android.permission.REPORT_SUPERUSER"
131 + android:protectionLevel="signature" />
134 + android:name="android.permission-group.SUPERUSER"
135 + android:description="@string/superuser_description_more"
136 + android:icon="@drawable/ic_action_permission"
137 + android:label="@string/superuser"
138 + android:priority="10000" />
141 + android:name="android.permission.ACCESS_SUPERUSER"
142 + android:description="@string/superuser_description_more"
143 + android:icon="@drawable/ic_action_permission"
144 + android:label="@string/superuser_description"
145 + android:logo="@drawable/ic_action_permission"
146 + android:permissionGroup="android.permission-group.SUPERUSER"
147 + android:protectionLevel="dangerous" />
149 <application android:label="@string/settings_label"
150 android:icon="@mipmap/ic_launcher_settings"
151 android:taskAffinity=""
153 android:hardwareAccelerated="true"
154 android:supportsRtl="true">
156 + <!-- Only system/su can open this activity -->
157 + <!-- This activity will then call the MultitaskSuRequestActivity to create a new task stack -->
159 + android:name="com.koushikdutta.superuser.RequestActivity"
160 + android:configChanges="keyboardHidden|orientation|screenSize"
161 + android:label="@string/superuser"
162 + android:launchMode="singleTask"
163 + android:noHistory="true"
164 + android:permission="android.permission.REQUEST_SUPERUSER"
165 + android:theme="@style/RequestTheme" />
166 + <!-- Only system/su can open this activity -->
167 + <!-- This is activity is started in multiuser mode when the user invoking su -->
168 + <!-- is not the device owner (user id 0). -->
170 + android:name="com.koushikdutta.superuser.NotifyActivity"
171 + android:configChanges="keyboardHidden|orientation|screenSize"
172 + android:label="@string/superuser"
173 + android:launchMode="singleTask"
174 + android:noHistory="true"
175 + android:permission="android.permission.REQUEST_SUPERUSER"
176 + android:theme="@style/RequestTheme" />
178 + <!-- Multiple instances of this activity can be running for multiple su requests -->
180 + android:name="com.koushikdutta.superuser.MultitaskSuRequestActivity"
181 + android:configChanges="keyboardHidden|orientation|screenSize"
182 + android:exported="false"
183 + android:label="@string/request"
184 + android:theme="@style/RequestTheme" />
187 + android:name="com.koushikdutta.superuser.SuReceiver"
188 + android:permission="android.permission.REPORT_SUPERUSER" />
193 <activity android:name="Settings"
194 diff --git a/proguard.flags b/proguard.flags
195 index 0805d68..bc0a933 100644
199 -keep class com.android.settings.accounts.*
200 -keep class com.android.settings.fuelgauge.*
201 -keep class com.android.settings.users.*
202 +-keep class com.koushikdutta.**
204 # Keep click responders
205 -keepclassmembers class com.android.settings.inputmethod.UserDictionaryAddWordActivity {
206 diff --git a/res/xml/settings_headers.xml b/res/xml/settings_headers.xml
207 index 156d63f..63b7077 100644
208 --- a/res/xml/settings_headers.xml
209 +++ b/res/xml/settings_headers.xml
211 <header android:id="@+id/system_section"
212 android:title="@string/header_category_system" />
216 + android:id="@+id/superuser"
217 + android:fragment="com.koushikdutta.superuser.PolicyNativeFragment"
218 + android:icon="@drawable/ic_action_permission"
219 + android:title="@string/superuser" />
223 android:id="@+id/date_time_settings"