README.md

   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
  10
  11 ## Checking out the source
  12
  13 You'll need the "Widgets" dependency.
  14
  15 * $ mkdir /path/to/src
  16 * $ cd /path/to/src
  17 * $ git clone git://github.com/koush/Superuser
  18 * $ git clone git://github.com/koush/Widgets
  19
  20 These repositories do not keep the actual projects in the top level directory.
  21 This is because they contain tests, libs, and samples.
  22
  23 ## Eclipse
  24
  25 In Eclipse, import Widgets/Widgets and Superuser/Superuser. It should Just Work (TM).
  26
  27 ## Ant
  28
  29 * $ mkdir /path/to/src
  30 * $ cd /path/to/src
  31 * $ cd Superuser/Superuser
  32
  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:
  34
  35 ```
  36 ndk.dir=/Users/koush/src/android-ndk
  37 ```
  38
  39 Then you can build:
  40
  41 * $ ant release
  42
  43 Outputs:
  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
  48
  49 ## Building the su binary
  50
  51 You can use ant as shown above, to build the binary, but it can also be built without building the APK.
  52
  53 Make sure you have the android-ndk downloaded with the tool "ndk-build" in your path.
  54
  55 * $ cd /path/to/src/
  56 * $ cd Superuser/Superuser
  57 * $ ndk-build
  58
  59 The su binary will built into Superuser/Superuser/libs/armeabi/su.
  60
  61
  62
  63 ## Building with AOSP, CyanogenMod, etc
  64
  65 ROM developers are welcome to distribute the official Superuser APK and binary that I publish. That will
  66 allow them to receive updates with Google Play. However, you can also build Superuser as part of your
  67 build, if you choose to.
  68
  69 There are two ways to include Superuser in your build. The easiest is to build the APK as a separate app.
  70 To do that, simply add the local_manifest.xml as described below. The second way is by embedding it
  71 into the native Android System Settings.
  72
  73 #### Repo Setup
  74 Add the [local_manifest.xml](https://github.com/koush/Superuser/blob/master/local_manifest.xml) to your .repo/local_manifests
  75
  76 #### Configuring the Package Name
  77 The Superuser distributed on Google Play is in the package name com.koushikdutta.superuser.
  78 To prevent conflicts with the Play store version, the build process changes the package
  79 name to com.thirdparty.superuser. You can configure this value by setting the following
  80 in your vendor makefile or BoardConfig:
  81
  82 ```
  83 SUPERUSER_PACKAGE := com.mypackagename.superuser
  84 ```
  85
  86 #### Advanced - Embedding Superuser into System Settings
  87
  88 You will not need to change the package name as described above. Superuser will simply go
  89 into the com.android.settings package.
  90
  91 First, in a product makefile (like vendor/cm/config/common.mk), specify the following:
  92
  93 ```
  94 SUPERUSER_EMBEDDED := true
  95 ```
  96
  97 To modify the Settings app, you will need this [patch](http://review.cyanogenmod.org/#/c/32957/).
  98 The patch simply references the sources checked out to external/koush and makes changes
  99 to XML preference files and the AndroidManifest.xml. It is a very minimal change:
 100
 101 ```diff
 102
 103 diff --git a/Android.mk b/Android.mk
 104 index fe8ed2d..6dea5b0 100644
 105 --- a/Android.mk
 106 +++ b/Android.mk
 107 @@ -13,6 +13,11 @@ LOCAL_CERTIFICATE := platform
 108
 109  LOCAL_PROGUARD_FLAG_FILES := proguard.flags
 110
 111 +LOCAL_AAPT_INCLUDE_ALL_RESOURCES := true
 112 +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 +
 114 +LOCAL_SRC_FILES += $(call all-java-files-under,../../../external/koush/Superuser/Superuser/src) $(call all-java-files-under,../../../external/koush/Widgets/Widgets/src)
 115 +
 116  include $(BUILD_PACKAGE)
 117
 118  # Use the folloing include to make our test apk.
 119 diff --git a/AndroidManifest.xml b/AndroidManifest.xml
 120 index 72be71b..4171800 100644
 121 --- a/AndroidManifest.xml
 122 +++ b/AndroidManifest.xml
 123 @@ -64,6 +64,29 @@
 124      <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
 125      <uses-permission android:name="android.permission.SET_TIME" />
 126
 127 +    <permission
 128 +        android:name="android.permission.REQUEST_SUPERUSER"
 129 +        android:protectionLevel="signature" />
 130 +    <permission
 131 +        android:name="android.permission.REPORT_SUPERUSER"
 132 +        android:protectionLevel="signature" />
 133 +
 134 +    <permission-group
 135 +        android:name="android.permission-group.SUPERUSER"
 136 +        android:description="@string/superuser_description_more"
 137 +        android:icon="@drawable/ic_action_permission"
 138 +        android:label="@string/superuser"
 139 +        android:priority="10000" />
 140 +
 141 +    <permission
 142 +        android:name="android.permission.ACCESS_SUPERUSER"
 143 +        android:description="@string/superuser_description_more"
 144 +        android:icon="@drawable/ic_action_permission"
 145 +        android:label="@string/superuser_description"
 146 +        android:logo="@drawable/ic_action_permission"
 147 +        android:permissionGroup="android.permission-group.SUPERUSER"
 148 +        android:protectionLevel="dangerous" />
 149 +
 150      <application android:label="@string/settings_label"
 151              android:icon="@mipmap/ic_launcher_settings"
 152              android:taskAffinity=""
 153 @@ -72,6 +95,41 @@
 154              android:hardwareAccelerated="true"
 155              android:supportsRtl="true">
 156
 157 +        <!-- Only system/su can open this activity -->
 158 +        <!-- This activity will then call the MultitaskSuRequestActivity to create a new task stack -->
 159 +        <activity
 160 +            android:name="com.koushikdutta.superuser.RequestActivity"
 161 +            android:configChanges="keyboardHidden|orientation|screenSize"
 162 +            android:label="@string/superuser"
 163 +            android:launchMode="singleTask"
 164 +            android:noHistory="true"
 165 +            android:permission="android.permission.REQUEST_SUPERUSER"
 166 +            android:theme="@style/RequestTheme" />
 167 +        <!-- Only system/su can open this activity -->
 168 +        <!-- This is activity is started in multiuser mode when the user invoking su -->
 169 +        <!-- is not the device owner (user id 0). -->
 170 +        <activity
 171 +            android:name="com.koushikdutta.superuser.NotifyActivity"
 172 +            android:configChanges="keyboardHidden|orientation|screenSize"
 173 +            android:label="@string/superuser"
 174 +            android:launchMode="singleTask"
 175 +            android:noHistory="true"
 176 +            android:permission="android.permission.REQUEST_SUPERUSER"
 177 +            android:theme="@style/RequestTheme" />
 178 +
 179 +        <!-- Multiple instances of this activity can be running for multiple su requests -->
 180 +        <activity
 181 +            android:name="com.koushikdutta.superuser.MultitaskSuRequestActivity"
 182 +            android:configChanges="keyboardHidden|orientation|screenSize"
 183 +            android:exported="false"
 184 +            android:label="@string/request"
 185 +            android:theme="@style/RequestTheme" />
 186 +
 187 +        <receiver
 188 +            android:name="com.koushikdutta.superuser.SuReceiver"
 189 +            android:permission="android.permission.REPORT_SUPERUSER" />
 190 +
 191 +
 192          <!-- Settings -->
 193
 194          <activity android:name="Settings"
 195 diff --git a/proguard.flags b/proguard.flags
 196 index 0805d68..bc0a933 100644
 197 --- a/proguard.flags
 198 +++ b/proguard.flags
 199 @@ -12,6 +12,7 @@
 200  -keep class com.android.settings.accounts.*
 201  -keep class com.android.settings.fuelgauge.*
 202  -keep class com.android.settings.users.*
 203 +-keep class com.koushikdutta.**
 204
 205  # Keep click responders
 206  -keepclassmembers class com.android.settings.inputmethod.UserDictionaryAddWordActivity {
 207 diff --git a/res/xml/settings_headers.xml b/res/xml/settings_headers.xml
 208 index 156d63f..63b7077 100644
 209 --- a/res/xml/settings_headers.xml
 210 +++ b/res/xml/settings_headers.xml
 211 @@ -213,6 +213,13 @@
 212      <header android:id="@+id/system_section"
 213          android:title="@string/header_category_system" />
 214
 215 +    <!-- Superuser -->
 216 +    <header
 217 +        android:id="@+id/superuser"
 218 +        android:fragment="com.koushikdutta.superuser.PolicyNativeFragment"
 219 +        android:icon="@drawable/ic_action_permission"
 220 +        android:title="@string/superuser" />
 221 +
 222      <!-- Date & Time -->
 223      <header
 224          android:id="@+id/date_time_settings"
 225
 226
 227 ```