Shizuku README

The project's README from github.com/RikkaApps/Shizuku. As one markdown file: README.md.

Shizuku

Background

When developing apps that requires root, the most common method is to run some commands in the su shell. For example, there is an app that uses the pm enable/disable command to enable/disable components.

This method has very big disadvantages:

  1. Extremely slow (Multiple process creation)
  2. Needs to process texts (Super unreliable)
  3. The possibility is limited to available commands
  4. Even if ADB has sufficient permissions, the app requires root privileges to run

Shizuku uses a completely different way. See detailed description below.

User guide & Download

https://shizuku.rikka.app/

How does Shizuku work?

First, we need to talk about how app use system APIs. For example, if the app wants to get installed apps, we all know we should use PackageManager#getInstalledPackages(). This is actually an interprocess communication (IPC) process of the app process and system server process, just the Android framework did the inner works for us.

Android uses binder to do this type of IPC. Binder allows the server-side to learn the uid and pid of the client-side, so that the system server can check if the app has the permission to do the operation.

Usually, if there is a "manager" (e.g., PackageManager) for apps to use, there should be a "service" (e.g., PackageManagerService) in the system server process. We can simply think if the app holds the binder of the "service", it can communicate with the "service". The app process will receive binders of system services on start.

Shizuku guides users to run a process, Shizuku server, with root or ADB first. When the app starts, the binder to Shizuku server will also be sent to the app.

The most important feature Shizuku provides is something like be a middle man to receive requests from the app, sent them to the system server, and send back the results. You can see the transactRemote method in rikka.shizuku.server.ShizukuService class, and moe.shizuku.api.ShizukuBinderWrapper class for the detail.

So, we reached our goal, to use system APIs with higher permission. And to the app, it is almost identical to the use of system APIs directly.

Developer guide

API & sample

https://github.com/RikkaApps/Shizuku-API

Migrating from pre-v11

Existing applications still works, of course.

https://github.com/RikkaApps/Shizuku-API#migration-guide-for-existing-applications-use-shizuku-pre-v11

Attention

  1. ADB permissions are limited

    ADB has limited permissions and different on various system versions. You can see permissions granted to ADB here.

    Before calling the API, you can use ShizukuService#getUid to check if Shizuku is running user ADB, or use ShizukuService#checkPermission to check if the server has sufficient permissions.

  2. Hidden API limitation from Android 9

    As of Android 9, the usage of the hidden APIs is limited for normal apps. Please use other methods (such as https://github.com/LSPosed/AndroidHiddenApiBypass).

  3. Android 8.0 & ADB

    At present, the way Shizuku service gets the app process is to combine IActivityManager#registerProcessObserver and IActivityManager#registerUidObserver (26+) to ensure that the app process will be sent when the app starts. However, on API 26, ADB lacks permissions to use registerUidObserver, so if you need to use Shizuku in a process that might not be started by an Activity, it is recommended to trigger the send binder by starting a transparent activity.

  4. Direct use of transactRemote requires attention

    • The API may be different under different Android versions, please be sure to check it carefully. Also, the android.app.IActivityManager has the aidl form in API 26 and later, and android.app.IActivityManager$Stub exists only on API 26.

    • SystemServiceHelper.getTransactionCode may not get the correct transaction code, such as android.content.pm.IPackageManager$Stub.TRANSACTION_getInstalledPackages does not exist on API 25 and there is android.content.pm.IPackageManager$Stub.TRANSACTION_getInstalledPackages_47 (this situation has been dealt with, but it is not excluded that there may be other circumstances). This problem is not encountered with the ShizukuBinderWrapper method.

Developing Shizuku itself

Build

The :manager:assembleDebug task generates a debuggable server. You can attach a debugger to shizuku_server to debug the server. Be aware that, in Android Studio, "Run/Debug configurations" - "Always install with package manager" should be checked, so that the server will use the latest code.

License

All code files in this project are licensed under Apache 2.0

Under Apache 2.0 section 6, specifically:

Shizuku (RikkaApps/Shizuku)

Searching Database…

31.8K ·GitHub
Shizuku
这是什么？Shizuku 让普通的 Android 应用通过 ADB 或 root 权限调用特权系统 API。它通过 app_process 运行一个小型 Java 服务进程，而不是通过 su 调用 shell 命令。
这是一个应用，还是我要添加到项目里的库？两者都是：Shizuku 是用户在设备上安装的管理应用（可通过 ADB 使用），同时它还提供一个库（ShizukuBinderWrapper、ShizukuService API），第三方应用开发者可以集成这个库，与该服务进程通信。
怎样才能让它运行起来？普通用户安装 Shizuku 管理应用，然后通过 ADB 或 root 启动服务；开发者则需要带子模块克隆仓库，并用 Gradle 构建管理模块（assembleDebug 或 assembleRelease）。
我需要 root 吗，还是 ADB 也可以？两种都可以：Shizuku 既能使用 ADB 权限运行，也能使用 root 权限运行，不过 ADB 权限更受限，并且会因 Android 版本不同而有所差异。
直接调用这些 API 时有什么需要注意的坑吗？在 Android 9 及以上版本，隐藏 API 受到限制；ADB 的权限集合因系统版本而异；API 26 的进程检测有一些特殊情况，需要变通处理；另外，直接调用 transactRemote 时使用的事务码，在不同 Android 版本之间可能不同。
这个许可证是完全开放的吗？采用 Apache 2.0 许可证，但附加了一条额外条款：禁止其他应用使用本应用的图标、“Shizuku”名称，或其应用 ID 与权限字符串。
为什么要用 Shizuku，而不直接通过 su 运行 shell 命令？通过 su 调用 shell 命令速度慢（每次都要启动多个进程），还需要对命令输出做容易出错的文本解析，而且能做的事情也只限于已有的命令。Shizuku 则运行一个常驻的 Java 服务进程，让应用直接调用真正的系统 API。
ShizukuBinderWrapper 是做什么用的？它是通过 Shizuku 调用系统服务 Binder 方法的推荐方式，并且能避免直接使用 transactRemote 时，因不同 Android 版本之间事务码不匹配而可能出现的问题。
没有 Activity 启动应用，Shizuku 还能正常工作吗？在 Android 8.0 上使用 ADB 时，进程检测依赖 registerUidObserver，而 ADB 在 API 26 上无法使用它。因此，对于可能在没有 Activity 的情况下启动的应用，建议触发一个透明的 Activity 来注册 Binder。
What are similar projects?timber, GSYVideoPlayer, MaterialDrawer, MVPArms, Vector, hilight-studio, butterknife, EventBus
Which topics is it in?adb, root, android-development, android-library, mobile-development, kotlin, mobile, android, security, apache-2.0, library, developer-tools
Creator
RikkaApps
Size
38.1 MB
Stars
31.8K
Updated
CommitJun 18Releasev13.6.0May 25
Age
9y
Commits · 90 Days