简介本资源为 Google Play 应用签名更新工具 PEPKPlay Encrypt Private Key的完整 Java 源码实现面向 Android 开发者、安全工程师及签名流程自动化需求者解决官方 PEPK 工具闭源、不可定制、难以集成到 CI/CD 流程中的实际痛点。压缩包含 2000 个文件其中 1999 个为 Java 源文件覆盖 TLS 协议处理TlsProtocol.java、国密与国际密码算法实现GOST3411_2012Digest.java、AESFastEngine.java、ThreefishEngine.java、X.509 证书路径验证PKIXCertPathReviewer.java、EC 公钥运算ECPoint.java等核心模块1 个说明性 TXT 文件整体体积仅 5.02MB代码结构清晰、模块职责明确便于二次开发与签名逻辑深度定制。目前已有 372 人学习下载读者可直接获取可编译运行的完整工程、理解 Google Play 签名链校验底层机制、复用密码学工具类并基于源码快速构建私有签名服务或适配新签名策略。1. 为什么改签 Google Play 应用时光有 APK 文件根本跑不通pepk 工具链的真实定位与不可替代性很多开发者在首次尝试更新已上架 Google Play 的应用签名时会陷入一个典型误区以为只要生成新的 keystore、用 jarsigner 或 apksigner 重签 APK 就能直接上传。结果是——上传失败报错You uploaded an APK that is not signed with the upload certificate甚至更隐蔽的Your APK or Android App Bundle is signed with the wrong key。这类错误背后不是签名流程错了而是Google Play 的签名体系早已从“单证书直签”演进为“上传密钥 签名密钥分离”的双层信任模型。pepkPlay Encrypt Private Key正是 Google 官方为解决这一模型下“安全迁移旧签名”而设计的专用工具它不处理 APK 构建也不替代 apksigner它的唯一使命是在离线、可控环境下将你持有的上传密钥upload key安全地“委托”给 Google Play 后端的签名密钥app signing key完成密钥链的可信绑定。这不是玄学操作而是 Google Play Console 强制要求的合规动作适用于所有需要更换签名密钥如原 keystore 丢失、泄露、过期或团队密钥轮换的存量应用升级场景。如果你正卡在“老包还在上架、新包必须接续签名、但 Play Console 死活不认新密钥”这个节点那么 pepk 不是可选项而是当前技术路径下唯一被官方支持、可审计、可回溯的落地入口。2. pepk 工具的本质不是签名器而是密钥委托协议的命令行实现2.1 为什么不能跳过 pepk从 Google Play 签名机制讲起Google Play 自 2017 年起全面推行 App Signing by Google PlayASBGP服务。启用后应用实际分发到用户设备的 APK/AAB 由 Google 持有的签名密钥app signing key签署而非开发者上传的密钥。开发者仅持有并使用上传密钥upload key——它只用于向 Play Console 提交新版本不参与最终用户安装包的签名。这种分离带来两大刚性约束上传密钥可轮换但签名密钥不可见、不可导出、不可替换一旦启用 ASBGP原始签名密钥即由 Google 托管开发者永远无法获取其私钥。更换上传密钥需显式授权若原上传密钥丢失或需更新必须通过 Play Console 的「设置 → 应用完整性 → 应用签名」页面发起密钥更换流程而该流程强制要求提交一个由 pepk 工具生成的加密密钥文件.pem作为“我确系该应用合法控制者并授权用新上传密钥接管”的密码学凭证。pepk 的核心作用就是执行这个授权协议它接收你的新上传密钥.jks 或 .pem 格式、旧上传密钥的证书.der 或 .pem、以及 Google 提供的公钥play-app-signing-public-key.pem通过 RSA-OAEP 加密和 SHA-256 哈希生成一个结构化、不可伪造的.pem委托文件。这个文件本质是一段 Base64 编码的 ASN.1 数据包含加密后的密钥指纹、时间戳、签名者身份等元信息Play 后端用其自有私钥解密验证后才允许将新上传密钥绑定至该应用的签名密钥链。提示pepk 不接触你的 app signing key也不生成任何 APK它只生成一份“数字委任状”。整个过程完全离线无需网络连接私钥永不离开本地机器。2.2 下载与校验 pepk 工具包避开镜像站陷阱的实操步骤Google 官方仅通过 Android Studio 的 SDK Manager 分发 pepk 工具不提供独立下载链接也不托管于 GitHub 或 Maven 仓库。常见误操作是搜索 “pepk download” 后误入非官方镜像站下载到篡改版或过期版本如 v1.0.0 仅支持旧版密钥格式v2.0.0 才兼容 ECDSA 密钥。正确路径如下# 步骤 1确保已安装 Android Studio建议 Arctic Fox 或更高版本 # 步骤 2打开 SDK Manager → SDK Tools 标签页 → 勾选 Google Play Licensing注意名称易混淆实际包含 pepk # 步骤 3点击 Apply 安装完成后工具位于 # macOS: ~/Library/Android/sdk/extras/google/play-pem/ # Windows: %LOCALAPPDATA%\Android\Sdk\extras\google\play-pem\ # Linux: ~/Android/Sdk/extras/google/play-pem/安装后务必校验工具完整性。官方未提供 SHA256 哈希值但可通过以下方式交叉验证# 进入 pepk 目录后检查关键文件存在性与权限 ls -l pepk.jar play-app-signing-public-key.pem # 正常应输出以 macOS 为例 # -rwxr-xr-x 1 user staff 1234567 1 Jan 00:00 pepk.jar # -rw-r--r-- 1 user staff 89012 1 Jan 00:00 play-app-signing-public-key.pem # 检查 Java 版本兼容性pepk 要求 Java 8–17推荐 OpenJDK 11 java -version # 输出应类似openjdk version 11.0.18 2023-01-17注意play-app-signing-public-key.pem是 Google 的根公钥用于验证委托文件签名。该文件随 pepk 工具包一同分发切勿自行替换或从第三方获取。若文件缺失或损坏重新通过 SDK Manager 安装即可。2.3 准备密钥材料三类文件缺一不可的生成逻辑pepk 运行依赖三个明确角色的密钥文件缺一不可且格式、用途严格限定文件类型生成方式用途格式要求常见错误新上传密钥new_upload_keykeytool -genkeypair -keystore new_upload.jks -alias upload -keyalg RSA -keysize 2048 -validity 10000你将用于后续所有版本上传的密钥.jks推荐或 PKCS#8.pem需-rfc参数用-keyalg EC生成 ECDSA 密钥时必须搭配 pepk v2.0.0否则报Unsupported key algorithm旧上传证书old_upload_certkeytool -exportcert -keystore old_upload.jks -alias upload -file old_upload.der证明你曾是该应用的合法上传者.der二进制或 Base64 PEM.pem导出时未加-rfc导致生成二进制 DER但脚本误当 PEM 处理解密失败Google 公钥play-app-signing-public-key.pemSDK Manager 自动提供验证委托文件合法性PEM 格式固定内容从非官方渠道下载导致公钥不匹配Play 后端拒绝解密生成示例以 JKS 为例# 生成新上传密钥强密码保护记牢 keytool -genkeypair \ -keystore new_upload.jks \ -storepass MyStrongPass123! \ -alias upload \ -keypass MyStrongPass123! \ -keyalg RSA \ -keysize 2048 \ -validity 10000 \ -dname CNUpload Key, OUDev, OMyApp, LBeijing, STBJ, CCN # 导出旧上传证书假设旧密钥为 old_upload.jks keytool -exportcert \ -keystore old_upload.jks \ -storepass OldPass456! \ -alias upload \ -file old_upload.der # 注意此处生成 .der非 .pem关键逻辑说明old_upload.der是旧密钥的证书含公钥不含私钥因此可安全传输。pepk 用它来比对旧密钥指纹确认你有权发起更换。new_upload.jks是新私钥全程不离开你的机器pepk 仅读取其公钥部分用于构造委托。3. 用 pepk 在本地跑通最小委托命令参数含义与执行验证3.1 最小可行命令一行跑通但必须理解每个开关以下命令是生成有效委托文件的最小完整形式适用于绝大多数 RSA 密钥场景java -jar pepk.jar \ --keystorenew_upload.jks \ --aliasupload \ --outputencrypted_private_key.pem \ --encryption-key-pathplay-app-signing-public-key.pem \ --signing-certold_upload.der逐参数解析与血泪经验--keystorenew_upload.jks指定新上传密钥文件路径。必须是 JKS 或 PKCS#12.p12格式PEM 私钥需额外加--rsa-key-path但 JKS 更稳定。--aliasupload密钥别名必须与keytool -list -v -keystore new_upload.jks中显示的 alias 一致。大小写敏感空格会报错。--outputencrypted_private_key.pem输出委托文件名。必须以.pem结尾Play Console 只认此扩展名。文件内容为 Base64 编码可直接文本查看。--encryption-key-pathplay-app-signing-public-key.pemGoogle 公钥路径。SDK Manager 安装后自带绝对路径更稳妥如/Users/me/Library/Android/sdk/extras/google/play-pem/play-app-signing-public-key.pem。--signing-certold_upload.der旧上传证书路径。必须是 DER 格式二进制若你只有 PEM 格式旧证书需先转换openssl x509 -in old_upload.pem -outform der -out old_upload.der。提示命令执行成功后终端无任何输出静默模式但会生成encrypted_private_key.pem。这是正常行为不代表失败。立即用cat encrypted_private_key.pem | head -n 5查看前几行确认以-----BEGIN ENCRYPTED PRIVATE KEY-----开头。3.2 验证输出文件有效性三步快速自检生成.pem后不要直接上传。先做本地验证避免因格式错误被 Play Console 拒绝第一步检查文件头尾是否符合 PEM 封装规范head -n 1 encrypted_private_key.pem # 应输出-----BEGIN ENCRYPTED PRIVATE KEY----- tail -n 1 encrypted_private_key.pem # 应输出-----END ENCRYPTED PRIVATE KEY-----第二步Base64 解码后检查长度防截断# 提取 Base64 内容去掉头尾行 sed 1d;$d encrypted_private_key.pem | tr -d \n | wc -c # 正常 RSA-2048 密钥委托文件解码后长度应在 1200–1800 字节之间。若 1000大概率生成失败。第三步用 OpenSSL 模拟解密需 Google 私钥不可行→ 改用间接法由于无法获取 Google 私钥我们转而验证委托文件的 ASN.1 结构是否合法# 安装 asn1parsemacOS 用 brew install openssl3Linux 用 apt install openssl openssl asn1parse -in encrypted_private_key.pem -i # 正常应输出多层嵌套结构顶层为 SEQUENCE包含 OBJECT IDENTIFIER (1.2.840.113549.1.1.1) 和 OCTET STRING。 # 若报错 Error in encoding 或 nested error, 说明 pepk 生成异常需检查输入密钥格式。血泪经验某开发者因old_upload.der实际是 PEM 格式但扩展名误写为 .der导致 pepk 读取时解析失败生成的.pem文件头正确但内容为空。自检第二步长度仅 23 字节立刻暴露问题。4. pepk 使用避坑指南5 条真实翻车记录与当场修复方案4.1 现象执行 pepk 命令后报错java.lang.UnsupportedClassVersionError: pepk has been compiled by a more recent version of the Java Runtime原因pepk.jar 编译目标为 Java 11字节码版本 55.0但本地java -version显示 Java 852.0或 Java 1761.0。Java 版本不兼容。解决统一使用 OpenJDK 11。macOS 用户brew install openjdk11 sudo ln -sfn /opt/homebrew/opt/openjdk11/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-11.jdkWindows 用户从 Adoptium 下载 JDK 11 MSI 安装包设JAVA_HOME指向新路径。4.2 现象上传encrypted_private_key.pem到 Play Console 后提示Invalid key file format原因--signing-cert参数指向了 PEM 格式证书如old_upload.pem而 pepk 要求 DER 格式。PEM 文件被当作二进制读取导致 ASN.1 解析失败。解决用 OpenSSL 转换openssl x509 -in old_upload.pem -outform der -out old_upload.der然后在 pepk 命令中改用--signing-certold_upload.der。4.3 现象生成的.pem文件可上传但 Play Console 卡在“正在处理”超过 2 小时最终失败原因新上传密钥new_upload.jks的密钥算法为 ECDSA-keyalg EC但使用的 pepk 版本过低 v2.0.0。旧版 pepk 仅支持 RSA。解决确认 pepk.jar 版本。进入 SDK Manager → 卸载 Google Play Licensing → 重启 Android Studio → 重新勾选安装。新版工具包内pepk.jar时间戳应为 2022 年 10 月之后。若仍无效改用 RSA 密钥重试。4.4 现象keytool -list -v -keystore new_upload.jks显示别名正确但 pepk 报错Keystore was tampered with, or password was incorrect原因--keystore密码与--storepass未显式传入。pepk 默认不提示输入密码而是直接失败。解决必须显式添加--storepass和--keypass参数即使两者相同java -jar pepk.jar \ --keystorenew_upload.jks \ --storepassMyStrongPass123! \ --keypassMyStrongPass123! \ --aliasupload \ --outputencrypted_private_key.pem \ --encryption-key-pathplay-app-signing-public-key.pem \ --signing-certold_upload.der4.5 现象Play Console 接收委托文件后显示“密钥更换已启动”但后续上传新 APK 仍报upload certificate mismatch原因密钥更换是异步流程需等待 Google 后端完成密钥链绑定。此过程通常需 24–72 小时期间旧上传密钥仍有效新密钥尚未激活。解决耐心等待。登录 Play Console → 应用 → 设置 → 应用完整性 → 应用签名查看状态栏。只有状态变为 “Your app is signed by Google” 且下方显示 “Upload key” 已更新为新密钥指纹时才可使用新密钥上传。此时可用keytool -printcert -jarfile app-release.aab | grep SHA256验证 APK/AAB 签名指纹是否匹配新密钥。5. 进阶技巧自动化密钥轮换流水线与委托文件安全归档5.1 将 pepk 集成进 CI/CD用 Bash 脚本封装全流程在团队协作中手动执行 pepk 易出错且不可审计。我一般会将密钥轮换封装为幂等脚本纳入 GitOps 流程。核心思路所有密钥材料存于加密 Vault脚本拉取后本地生成委托文件上传至 Play Console 前自动校验。以下是精简版 CI 脚本骨架适配 GitHub Actions#!/bin/bash # pepk-rotate.sh密钥轮换主脚本 set -e # 任一命令失败即退出 # 1. 从 Secrets 注入密钥生产环境严禁明文 echo ${NEW_UPLOAD_JKS_BASE64} | base64 -d new_upload.jks echo ${OLD_UPLOAD_DER_BASE64} | base64 -d old_upload.der # 2. 校验密钥完整性 keytool -list -v -keystore new_upload.jks -storepass ${NEW_STORE_PASS} | grep Certificate fingerprint /dev/null openssl asn1parse -in old_upload.der -i /dev/null # 3. 执行 pepk显式指定 Java 11 JAVA_HOME/opt/java/openjdk11 \ java -jar $ANDROID_HOME/extras/google/play-pem/pepk.jar \ --keystorenew_upload.jks \ --storepass${NEW_STORE_PASS} \ --keypass${NEW_KEY_PASS} \ --aliasupload \ --outputencrypted_private_key.pem \ --encryption-key-path$ANDROID_HOME/extras/google/play-pem/play-app-signing-public-key.pem \ --signing-certold_upload.der # 4. 上传前二次校验 if [ $(wc -c encrypted_private_key.pem | awk {print $1}) -lt 1000 ]; then echo ERROR: Generated pem too small. Aborting. exit 1 fi # 5. 安全归档生成带哈希与时间戳的归档包 tar -czf pepk-$(date %Y%m%d-%H%M%S).tar.gz \ new_upload.jks \ old_upload.der \ encrypted_private_key.pem \ play-app-signing-public-key.pem sha256sum pepk-$(date %Y%m%d-%H%M%S).tar.gz pepk-$(date %Y%m%d-%H%M%S).sha256关键设计点set -e确保任一环节失败立即终止避免脏数据残留所有密钥通过base64注入规避 shell history 泄露归档包包含全部输入输出文件及校验哈希满足审计要求时间戳命名防止覆盖便于回溯。5.2 委托文件的安全归档为什么不能只存.pem很多团队只保存生成的encrypted_private_key.pem认为它是“最终产物”。这是重大隐患。委托文件本身不包含密钥指纹、时间戳、旧证书哈希等上下文一旦 Play Console 状态异常无法快速定位是哪次轮换出了问题。我坚持归档四件套文件作用保留期限存储建议new_upload.jks加密新上传密钥源文件永久企业 VaultAES-256 加密old_upload.der旧证书原始证据永久同上与新密钥分开存储encrypted_private_key.pem委托凭证永久同上但需标记“已上传至 Play Console”状态pepk-run.log完整执行日志含命令、时间、exit code3 年日志系统按应用 ID 索引归档时我会用sha256sum对四件套生成总哈希并将哈希值写入 Confluence 文档文档权限设为“仅密钥管理员组可读”。这样当某天需要复核“2024Q2 的密钥轮换是否合规”只需查文档哈希再比对 Vault 中对应归档包哈希5 秒内完成验证。5.3 一次失败的教训把 pepk 当作“重签名工具”的代价去年某项目A同学误以为 pepk 可以绕过 Google Play 的签名限制试图用它“重签”一个未启用 ASBGP 的老应用。他生成了委托文件却在 Play Console 的“应用签名”页面找不到“更换上传密钥”入口——因为该应用从未开启 App Signing by Google Play。他反复尝试浪费 3 天最后才发现pepk 仅适用于已启用 ASBGP 的应用。对于未启用的应用必须先在 Play Console 中手动开启会生成 Google 托管的签名密钥再进行密钥轮换。这个翻车让我养成了一个硬习惯每次执行 pepk 前必开 Play Console截图保存“应用签名”页面状态栏。如果状态是 “You are managing your own app signing key”立刻停手先去开启 ASBGP。省下的不是 3 天而是团队对流程可靠性的信任。希望帮到你。本文还有配套的精品资源点击获取