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