KernelPatch 快速参考

2026-06-29 · 阅读 0

核心概念速查

三大组件

组件	位置	运行环境	主要功能
kptools	`tools/`	用户空间	修补内核镜像
kpimg	`kernel/`	内核空间	接管启动，提供 hook
kpuser	`user/`, `user_deprecated/`	用户空间	与 kpimg 通信

关键偏移量速查

偏移量	含义	典型值	用途
`setup_offset`	kpimg 在镜像中的位置	0x1ab3000	setup_preset 位置
`start_offset`	kpimg 运行时物理偏移	0x1ca6000	避免覆盖内核
`map_offset`	临时代码注入位置	0xd73550	tcp_init_sock
`kallsyms_lookup_name_offset`	符号查找函数偏移	0x982b0	查找符号
`paging_init_offset`	paging_init 偏移	0x1abe5d0	劫持点
`sprintf_offset`	sprintf 函数偏移	-	符号锚点扫描（0.13.0+）
`symbol_lookup_anchor_offset`	符号扫描锚点偏移	-	运行时定位 kallsyms（0.13.0+）

启动流程速查

Bootloader
  ↓
setup_entry (setup1.S)
  ↓
start_prepare() - 备份 tcp_init_sock，复制 kpimg
  ↓
map_prepare() - 劫持 paging_init，覆盖 tcp_init_sock
  ↓
恢复头部，跳转到 _head
  ↓
内核启动 → paging_init()
  ↓
_paging_init (map.c) - 分配内存，映射 kpimg
  ↓
start() (start.c) - 初始化，恢复 tcp_init_sock
  ↓
patch() (patch.c) - 安装 hooks
  ↓
内核继续启动（KernelPatch 已激活）

常用命令速查

kptools 命令

# 修补内核
kptools -p -i Image -k kpimg -s key -o Image.patched

# 嵌入 KPM
kptools -p -i Image -k kpimg -s key -M mod.kpm -T kpm -o out.img

# 导出符号
kptools -d -i Image > symbols.txt

# 导出 ikconfig（0.13.0+）
kptools -f -i Image

# 查看 patch 信息
kptools -l -i Image.patched

# 还原镜像
kptools -u -i Image.patched -o Image.orig

# boot.img 操作（0.13.0+）
kptools unpack boot.img       # 解包提取 kernel
kptools repack boot.img       # 重打包为 new-boot.img
kptools sha1 file             # 计算 SHA1 哈希

kpatch 命令

# 验证安装
kpatch key hello

# 获取 root
kpatch key su

# 加载 KPM
kpatch key kpm load /path/to/module.kpm

# 列出模块
kpatch key kpm list

# 查看版本
kpatch key kpver

# 查看日志
kpatch key bootlog

# 管理 SuperKey
kpatch key key get
kpatch key key set newkey

Hook 接口速查

函数 Hook

// Hook 4 参数函数
void before(hook_fargs4_t *args, void *udata) {
    args->arg0 = new_value;  // 修改参数
    args->skip_origin = 1;   // 跳过原函数
}

void after(hook_fargs4_t *args, void *udata) {
    args->ret = new_ret;     // 修改返回值
}

hook_wrap4(func_addr, before, after, udata);

// 其他参数数量：hook_wrap0/8/12

系统调用 Hook

// Hook execve
unsigned long execve_addr = kallsyms_lookup_name("__arm64_sys_execve");
hook_wrap3((void *)execve_addr, before_execve, 0, 0);

// 或修改 syscall table
sys_call_table[__NR_openat] = (uintptr_t)my_openat;

SuperCall 命令速查

命令	值	权限级别	功能
`SUPERCALL_HELLO`	0x1000	无需认证	验证安装
`SUPERCALL_KLOG`	0x1004	无需认证	printk 日志
`SUPERCALL_KERNELPATCH_VER`	0x1008	无需认证	KP 版本
`SUPERCALL_KERNEL_VER`	0x1009	无需认证	内核版本
`SUPERCALL_AP_LOAD_PACKAGE_CONFIG`	0x100d	无需认证	加载包配置（0.13.0+）
`SUPERCALL_SKEY_GET`	0x100a	is_authed	获取 key
`SUPERCALL_SKEY_SET`	0x100b	is_authed	设置 key
`SUPERCALL_SU`	0x1010	trusted_caller	SU 提权
`SUPERCALL_KPM_LOAD`	0x1020	is_authed	加载模块
`SUPERCALL_KPM_UNLOAD`	0x1021	is_authed	卸载模块
`SUPERCALL_KPM_NUMS`	0x1022	trusted_caller	模块数量
`SUPERCALL_KSTORAGE_WRITE`	0x1040	trusted_caller	写内核存储
`SUPERCALL_KSTORAGE_READ`	0x1041	trusted_caller	读内核存储

认证层次: SuperKey/trusted_manager(is_authed) > su_allow_uid(trusted_caller) > 未认证

KPM 开发速查

最小 KPM

#include <kpmodule.h>

KPM_NAME("my-module");
KPM_VERSION("1.0.0");
KPM_LICENSE("GPL v2");

static long my_init(const char *args, const char *event, void *reserved)
{
    pr_info("Module loaded\n");
    return 0;
}

KPM_INIT(my_init);

编译 KPM

export TARGET_COMPILE=aarch64-none-elf-
aarch64-none-elf-gcc -c module.c -I../../kernel/include -o module.o
aarch64-none-elf-ld -r -T module.lds module.o -o module.kpm

ARM64 指令速查

指令	格式	范围	用途
`B label`	imm26	±128MB	跳转
`BL func`	imm26	±128MB	调用
`B.cond label`	imm19	±1MB	条件跳转
`ADR Xd, label`	imm21	±1MB	地址计算
`ADRP Xd, page`	imm21	±4GB	页面地址
`LDR Xt, =data`	imm19	±1MB	PC 相对加载
`CBZ Xt, label`	imm19	±1MB	比较并跳转

内存权限速查

段	权限	PTE 标志	用途
text	R-X	`RDONLY & ~PXN`	代码段
data	RW-	`~RDONLY & PXN`	数据段
hook	RWX	`~RDONLY & ~PXN`	动态代码
rw_mem	RW-	`~RDONLY & PXN`	通用内存
rox_mem	R-X	`RDONLY & ~PXN`	只读代码

常见错误速查

错误	可能原因	解决方案	文档
`no symbol kallsyms_lookup_name`	未开启 CONFIG_KALLSYMS	检查内核配置	02, 03
`patch overlap`	kpimg 太大	正常，自动调整	04
`unresolved symbol`	KPM 符号未找到	使用 kallsyms_lookup_name	11
内核崩溃（PC 在 hook 段）	BTI bug	修复 setup1.S	15
`socket` 相关崩溃	tcp_init_sock 未恢复	检查 restore_map	14, 15
`SuperKey verification failed`	Key 错误	检查 key 拼写	10, 12

调试命令速查

# 查看内核日志
adb shell dmesg | grep "KP"

# 查看启动日志
adb shell kpatch key bootlog

# 查看符号
kptools -d -i Image | grep function_name

# 查看 patch 信息
kptools -l -i Image.patched

# 测试 SuperCall
adb shell kpatch key hello

# 验证 root
adb shell kpatch key su -c id

关键数据结构速查

// preset_t
typedef struct {
    setup_header_t header;        // 64 B
    setup_preset_t setup;         // ~960 B
} preset_t;

// hook_t
typedef struct {
    uint64_t func_addr;           // 函数地址
    uint64_t origin_addr;         // Hook 点
    uint64_t replace_addr;        // Trampoline
    uint64_t relo_addr;           // 重定位地址
    uint32_t origin_insts[3];     // 原始指令
    // ...
} hook_t;

// kpm_t
typedef struct {
    char name[32];                // 模块名
    kpm_init_t init;              // 初始化函数
    kpm_exit_t exit;              // 退出函数
    void *base;                   // 内存基地址
    unsigned int size;            // 大小
    // ...
} kpm_t;

紧急修复清单

如果遇到 BTI 崩溃

✅ 编辑 kernel/base/setup1.S（221-249 行）
✅ 删除所有 BTI 检测代码
✅ 只保留：ldr w12, [x13] 和 str w12, [x9, ...]
✅ 重新编译：cd kernel && make clean && make
✅ 重新 patch：kptools -p -i Image -k kpimg -s key -o out.img
✅ 测试：刷入设备并查看日志

详见：15-问题排查与修复.md

联系与支持

Issues：报告问题和 bug
Discussions：讨论技术问题
Pull Requests：贡献代码和文档改进

返回索引：README.md

开始学习：01-项目概述.md

还没有评论，来说点什么吧。

核心概念速查

三大组件

关键偏移量速查

启动流程速查

常用命令速查

kptools 命令

kpatch 命令

Hook 接口速查

函数 Hook

系统调用 Hook

SuperCall 命令速查

KPM 开发速查

最小 KPM

编译 KPM

ARM64 指令速查

内存权限速查

常见错误速查

调试命令速查

关键数据结构速查

紧急修复清单

如果遇到 BTI 崩溃

联系与支持

评论