SuperKey authentication
About 1105 wordsAbout 4 min
SuperKey is YukiSU's optional manager identity authentication. It lets custom-signed, private or specialized managers prove to the kernel that the caller may become the YukiSU manager when the default APK-signature path is not suitable.
Normal users do not need it. The trusted official package and APK signature remain the default and simplest trust path.
Scope
YukiSU SuperKey authenticates only the manager. It is neither an application root password nor a universal credential that directly executes arbitrary privileged kernel commands. Superuser grants and App Profile still decide application access.
Different from KernelPatch / APatch SuperKey
The name is shared, but the call model and scope are not.
| Area | YukiSU SuperKey | KernelPatch / APatch SuperKey |
|---|---|---|
| Entry | prctl(KSU_PRCTL_SUPERKEY_AUTH, ...) | syscall NR45 SuperCall |
| Authenticates | YukiSU manager identity | Caller of each SuperCall |
| Scope | Verify key and record manager UID | Credential for a general privileged command plane |
| Operations after auth | Manager continues through YukiSU driver/ioctl | NR45 dispatches root, KPM, configuration and other commands |
| Direct application root | No | Depends on the selected SuperCall command |
KernelPatch/APatch carries SuperKey into NR45 to protect a family of SuperCall operations. YukiSU does not copy that interface. Its manager submits the key through a dedicated prctl authentication request; the kernel establishes manager identity, then authorization, modules and configuration continue through YukiSU's management interface.
The two keys are not interchangeable. APatch instructions for supercall, KPM or “SuperKey root” do not apply to YukiSU.
Trust configurations
| SuperKey | APK signature verification | Available path | Intended use |
|---|---|---|---|
| Empty | Enabled | Trusted package and APK signature | Official builds and first install; recommended |
| Set | Enabled | Signature remains available; SuperKey is added | Keep official fallback with a custom manager |
| Set | Disabled | SuperKey only | Closed private deployment; high risk |
“Disable APK signature verification” is a separate installation option. Setting a key does not disable signature authentication automatically.
Do not use SuperKey-only to hide an ordinary auth failure
If the official APK cannot authenticate, inspect its source, package/signature, YukiSU LKM and version combination first. Disabling signatures hides the original problem and makes recovery depend entirely on one credential.
The kernel does not keep plaintext
When configured, YukiSU creates a random 16-byte salt and stores the first eight bytes of SHA-256(salt || key) as the verifier, together with the authentication mode. Runtime verification recomputes the value from the submitted key and stored salt.
The final LKM therefore does not need a directly readable plaintext SuperKey, but it still contains material for offline analysis. Short or predictable keys remain guessable, and a private .ko, patched image or build artifact must still be treated as sensitive.
Provisioning the key
At build time, pass:
KSU_SUPERKEY="your-secret"Build automation must keep the original key out of command echo, CI parameters, artifact metadata and archived logs.
During patching or installation, enter SuperKey on the manager's LKM page. ksud writes the corresponding authentication data into that output only; existing images and .ko files are not modified retroactively.
CONFIG_KSU_SUPERKEY=y controls kernel support and is enabled in normal current configurations. A visible manager input does not prove that an arbitrary third-party or old LKM supports it; verify the installed state.
How authentication works
- The manager creates a request containing SuperKey, a Unix-seconds timestamp, result field and returned fd.
- It calls
prctl(KSU_PRCTL_SUPERKEY_AUTH, ...). - YukiSU's TSR path intercepts this dedicated request.
- The kernel verifies time, authentication mode and key.
- On success it records the caller UID as manager UID and supplies the manager driver fd.
- Subsequent management requests use the driver interface rather than passing SuperKey to every root command.
prctl provides a first-authentication path usable under Android seccomp. The current manager retains compatibility handling after it already has a driver fd, but the public model is unchanged: YukiSU SuperKey authenticates the manager and is not an NR45 general SuperCall.
The kernel rejects future timestamps, requests older than 30 seconds, mismatched or truncated keys, and requests when no SuperKey was configured. A badly wrong device clock can therefore reject a correct key. Authentication state belongs to the running kernel and must be established again after reboot.
Failed-attempt protection
In the current implementation, three consecutive failures terminate the authenticating process; ten total failures trigger a device reboot. Do not treat a real device as an unlimited password-guessing target.
Storage and boot authentication
- Do not store SuperKey: the manager retains no original key and requires manual input after reboot.
- Authenticate SuperKey at boot: the manager uses a saved key for one authentication attempt after startup. App autostart permission is required and failure is not retried indefinitely.
Manager-side storage of the original input is separate from the salt and verifier embedded in the LKM.
Choosing and protecting a key
- Use a sufficiently long, random, per-device value.
- Never reuse a lock-screen PIN, account password, ADB key passphrase or disk password.
- Avoid names, device models, project names and predictable phrases.
- Prefer characters that can be entered reliably on the device keyboard.
- Store it in a secure password manager with the corresponding device and LKM noted.
- Never expose plaintext in public scripts, shell history, CI logs or issue reports.
Public release builds should normally rely on official signature authentication without a private SuperKey. Personal and small deployments should separate keys by device or environment so that one leaked artifact does not affect every installation.
Rotating or removing a key
The verifier is part of the LKM trust configuration; changing an app setting cannot rotate it.
- Keep stock images and a bootable LKM matching current firmware.
- Build or patch a new LKM with the new key.
- Decide whether APK signature authentication remains enabled.
- Install through the normal LKM flow to a verified slot.
- Reboot and authenticate with the new key.
- Remove the old key and artifacts containing its verifier.
Returning to signature-only trust also requires an LKM with that trust configuration. Reinstalling only the APK is insufficient.
Troubleshooting
Check whether Home can read the YukiSU LKM, the LKM actually has SuperKey configured, the input has no surrounding spaces or full-width variants, device time is correct, the manager is the intended build, manual authentication is still required after reboot, and app autostart restrictions blocked automatic authentication.
If signature authentication remains enabled, use the trusted official manager and install an LKM with a known trust configuration. If signatures were disabled and the key is lost, there is no password-recovery path in the current LKM; restore trust using a compatible LKM or stock image matching the device, firmware and KMI.
Copyright
Copyright Ownership:Anatdx
License under:Attribution-NonCommercial-ShareAlike 4.0 International (CC-BY-NC-SA-4.0)