企业官网建设流程全解析

SwiftSlate 是一款 Android 系统级AI 文本转换工具：在任意应用里输入?fix等触发词，即可调用 Gemini、Groq 或任意 OpenAI 兼容端点实时改写文本。由于功能依赖 API 密钥，密钥如何安全存储成了核心问题。本文完整拆解 SwiftSlate 用Android Keystore 生成不可导出密钥、配合AES-256-GCM 加密存储API 密钥的实现方案，从密钥生成、密文格式、版本兼容到性能缓存，一次讲清。

一、为什么 API 密钥必须加密存储

API 密钥等于你的账户"钱包卡"：泄露后可能被他人盗用配额，甚至产生计费。SwiftSlate 的密钥要长期落在本地磁盘上，而 Android 的 SharedPreferences 文件本身是明文 XML——直接写入密钥，任何能读到应用数据目录的人（root、恶意备份、设备转卖）都能直接看到。

SwiftSlate 的设计目标是：密钥永远不以明文形式落盘，且解密密钥本身永远离开不了设备安全硬件。

二、总体架构：三层安全防线

整个方案由三个模块协作完成，职责清晰分离：

加密引擎被抽象成KeyCipher接口（见 KeyCipher.kt#L21-L30），真正的实现AndroidKeystoreCipher只关心一件事：让密钥的生成、加密、解密全部发生在 Keystore 的安全边界内，应用内存中拿不到原始密钥字节。

三、第一步：在 Android Keystore 生成不可导出的 AES-256 密钥

AndroidKeystoreCipher初始化时，若 Keystore 中不存在名为typeslate_secure_key的密钥，就现场生成一个（KeyCipher.kt#L55-L95）：

KeyGenParameterSpec.Builder( KEY_ALIAS, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT ) .setBlockModes(KeyProperties.BLOCK_MODE_GCM) .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE) .setKeySize(256)

三个关键参数的含义：

• PURPOSE_ENCRYPT or PURPOSE_DECRYPT：密钥仅限加密/解密用途，不能被挪作他用；
• BLOCK_MODE_GCM+ 无填充：指定 GCM 模式，自带完整性校验（后面详述为什么不用 CBC）；
• setKeySize(256)：256 位密钥，即 AES-256 强度。

由于密钥由AndroidKeyStore提供者直接生成，它被保存在设备的安全硬件（TEE/Secure Element）中，不可导出、不可读出——即使有人拿到应用数据目录，也只能拿到一堆无法解开的密文。

🔐额外一层保险：在 Android 15（API 35）及以上，还会启用setUnlockedDeviceRequired(true)（KeyCipher.kt#L87-L91）。密钥只在设备解锁后可用——锁屏状态下即使数据被拷走也无法解密。

为什么只在 Android 15+ 启用？

这是一个非常务实的取舍。源码注释写得很直白（KeyCipher.kt#L70-L85）：Android 12/13/14 存在平台 Bug——带有该标记的密钥在用户移除安全锁屏后会被系统静默删除，导致已存储的密钥永远无法解密。与其换来"锁屏加固"的收益、却让用户在三代主流系统上彻底丢失密钥，不如只在 Google 官方确认修复的 Android 15+ 上启用。

四、加密流程：AES/GCM/NoPadding 与自定义密文格式

加密函数只有十行（KeyCipher.kt#L115-L123），核心流程：

1. 用 Keystore 密钥初始化AES/GCM/NoPadding的Cipher；
2. 取出自动生成的随机 IV（初始化向量），Base64 编码；
3. 执行doFinal加密，输出同样是 Base64 编码；
4. 拼成最终格式：Base64(IV)]Base64(密文+认证标签)。

为什么选 GCM 而不是更常见的 CBC？GCM 模式在加密的同时输出 128 比特的认证标签（GCM_TAG_BITS = 128，见 KeyCipher.kt#L39）。解密时（KeyCipher.kt#L125-L138）会用标签校验密文是否被篡改：

• 密钥错了、文件损坏、或数据被人为改动 → 校验失败 →decrypt返回null；
• 应用据此明确知道"这份数据解不开"，而不是得到一串乱码。

一个巧妙的细节：分隔符选用了]。Base64（无换行）只会输出A-Za-z0-9+/=，绝不含]，因此"IV | 密文"的边界永远不会歧义。

五、旧版本明文密钥的无缝迁移

早期版本的 SwiftSlate 把密钥以明文 JSON 数组（如["sk-xxx"]）直接存在 SharedPreferences 里。升级为加密版本后，KeyManager 在读取时自动识别并原地迁移：

• 判断是否为旧格式：stored.trimStart().startsWith("[")（KeyManager.kt#L36）——密文以 Base64 开头，永远不会以[打头，两种形态绝无歧义；
• 识别到明文后，立即加密回写 prefs，用户无感完成升级，不丢一个密钥。

这里的判断逻辑本身还修过一个隐蔽 Bug：最初用的是!stored.contains("]")，而["key"]这个明文 JSON 恰好含有]，会被误判成密文送去解密，导致老用户升级后所有密钥"凭空消失"。改用"是否以[开头"后问题根除。

六、性能优化：5 秒缓存与密文比对

Android Keystore 的加解密每次都要走系统 HAL 通道，而无障碍服务在用户打字时高频取密钥。SwiftSlate 用两级策略避免反复解密（KeyManager.kt#L62-L96）：

配合进程级单例（SwiftSlateApp.kt#L25），UI 与无障碍服务共享同一份状态，既安全又流畅。

七、失败处理：加密失败时绝不回退明文

这是整个方案最关键的一条铁律：宁可不存，也不能明文存。

• saveKeys中加密抛异常时，直接返回失败并清空缓存（KeyManager.kt#L104-L119），UI 在 Keys 页面展示 Keystore 不可用提示，用户能明确感知而不是静默降级；
• 测试用例keysAreNotStoredInPlaintext专门断言：存入的密钥在任何情况下都不能以明文出现在 prefs 文件中（KeyManagerTest.kt#L114-L120）。

最后一道防线在备份层面：backup_rules.xml 显式将secure_keys_prefs.xml排除在 Android 云备份之外——即使密文本身安全，SwiftSlate 也不愿让它出现在任何备份介质里。

八、多密钥轮换：加密之外的第二道保险

密钥解出后并不是一次性使用。KeyManager 还实现了多密钥智能调度，降低单密钥失效的影响面：

• 轮询使用：多个密钥 round-robin 轮流请求，配额均匀分摊；
• 限流冷却：收到 429 的密钥自动进入冷却期（最长 600 秒）；
• 无效标记自愈：401/403 的密钥暂停 15 分钟后自动恢复尝试，避免一次瞬时 403 把密钥"杀死"到进程重启。

九、小结：这套加密存储方案的 6 个亮点

值得一提的是，整个加密层被KeyCipher接口隔离，测试中用FakeCipher替换真实 Keystore（KeyManagerTest.kt#L21-L43），让这套安全关键路径真正跑进了 CI——而不是一遇到模拟器环境就"跳过测试、假装通过"。

核心文件索引：

• 加密实现：KeyCipher.kt
• 存储与轮换：KeyManager.kt
• 云备份排除：backup_rules.xml
• 安全测试：KeyManagerTest.kt

这套方案证明了：在移动端做好密钥安全，不需要任何第三方安全 SDK——理解 Android Keystore 的能力边界、选对 GCM 模式、把"失败"当成一级公民来设计，就能构建出既坚固又优雅的加密存储。