[Keystore] 命名密钥与证书

本节用于声明按名称引用的 SSH 私钥与 PKCS#12（P12）证书凭据材料。Proxy 的 private-key 和 MITM 的 ca-keystore-name 使用这些名称获取凭据。

语法声明块

条目通过标准的 INI 配置行进行声明：

[Keystore]
name = kind, base64=<SECRET>, [options...]

各组成部分解析如下：

• name：凭据的唯一命名标识，供 [Proxy] 或 [MITM] 引用。
• kind：凭据用途类型（位置参数，必填），可选 private-ssh-key（或 openssh-private-key）、p12。
• base64：Base64 编码的密钥或证书归档材料内容。
• [options...]：可选键值参数（如 password）。

字段详解

• name（非空字符串，必填） 凭据的唯一引用名称。不包含空字符（NUL），UTF-8 编码长度最多 255 字节。
• kind（枚举值，必填） 凭据用途类型（第一个位置参数）：
  • private-ssh-key / openssh-private-key：SSH 私钥材料，供 Proxy 的 private-key 引用；
  • p12：PKCS#12 证书与私钥归档材料，供 MITM 的 ca-keystore-name 引用。
• base64（Base64 编码字符串，必填） 编码后的完整私钥文件或 PKCS#12 归档文件数据。配置解析时校验 Base64 解码有效性。
• password（字符串，未设置） 解锁受保护 SSH 私钥或 PKCS#12 归档所需的解密密码。若密码包含逗号或等号等特殊字符，需使用双引号整体包裹。

配置约束与合并规则

• 名称唯一：同一配置层内禁止声明同名条目。
• 引用范围：仅支持 Proxy 的 private-key 与 MITM 的 ca-keystore-name 按名称引用，不执行全局变量或文本替换。
• 插件覆盖：插件中声明同名条目时，按名称整体覆盖基础配置中的条目，材料与选项不执行逐字段合并。支持在章节首行声明 %INSERT% 或 %APPEND%。

基于 Keychain 的凭据

在 Apple 平台中，敏感凭据可通过应用管理界面导入至系统 Keychain，由系统加密保护并持久化存储：

• 系统安全加密存储：私钥与证书归档材料由系统 Keychain 加密保护，避免在配置文件中以明文或 Base64 形式暴露敏感密钥信息。
• 命名引用：导入 Keychain 的条目以其设置的名称作为标识，Proxy 的 private-key 与 MITM 的 ca-keystore-name 可直接通过该 name 进行引用，无需在 [Keystore] 配置节中声明材料。
• 解析优先级高于配置：解析命名凭据时，系统优先从 Keychain 安全存储中按名称查询；仅在 Keychain 中不存在该条目时，才会回退读取当前配置文件 [Keystore] 节中的同名条目。
• 失败不回退：若 Keychain 中已存在同名条目，但发生凭据损坏、用途不匹配（如将 SSH 私钥用于 MITM）或校验失败，系统直接返回错误，不会降级回退至 [Keystore] 节。

配置示例

1. 配置内声明凭据

[Keystore]
# SSH 私钥材料（无密码保护）
ssh-key = private-ssh-key, base64=<SECRET>

# P12 证书与私钥归档（带密码保护）
ca-cert = p12, base64=<SECRET>, password="<SECRET>"

[Proxy]
# SSH 出站引用命名私钥
SSH = ssh, proxy.example.com, 22, username=user, private-key=ssh-key

[MITM]
# HTTPS 解密引用命名 CA 证书
ca-keystore-name = ca-cert

2. 引用 Keychain 凭据

若已通过系统应用界面向 Keychain 导入名为 my-ssh-key 和 my-ca-cert 的凭据，配置中无需声明 [Keystore] 节，直接按名称引用即可（即便存在同名 [Keystore] 条目，也优先使用 Keychain 中的凭据）：

[Proxy]
SSH = ssh, proxy.example.com, 22, username=user, private-key=my-ssh-key

[MITM]
ca-keystore-name = my-ca-cert