5.2. 向 Agent 添加密钥 (Adding Keys to the Agent)

可以通过 SSH_AGENTC_ADD_IDENTITY 或 SSH_AGENTC_ADD_ID_CONSTRAINED 向 agent 添加密钥. 受约束变体会增加 constraint[] constraints 字段, 用于在保存密钥时附加使用限制.

本文档定义 DSA (ssh-dss), ECDSA (ecdsa-sha2-*), EdDSA (ssh-ed25519, ssh-ed448), RSA (ssh-rsa), 其他供应商特定密钥类型, 以及智能卡或硬件令牌中密钥的格式.

对于托管在令牌中的密钥, SSH_AGENTC_ADD_SMARTCARD_KEY 和 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED 会携带 token id, PIN 和可选约束. 如果成功加载一个或多个密钥, agent MUST 返回 SSH_AGENT_SUCCESS; 如果未找到密钥, 令牌未识别, 策略拒绝请求, 或不支持托管在令牌中的密钥, 则返回 SSH_AGENT_FAILURE.

添加普通私钥和添加 token-hosted key 的主要区别在于密钥材料的位置. 普通 key 消息会把 key type 和对应 private key 字段发送给 agent; token-hosted key 消息则只传递 token 标识、PIN 和约束, 实际私钥仍留在 smart card 或 hardware token 中. 因此, 实现必须按 key type 精确解析字段顺序, 同时避免在日志或错误消息中泄露 PIN、private key material 或 token-specific secret.

SSH_AGENTC_ADD_ID_CONSTRAINED 和 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED 的 constraints 会限制后续使用该 key 的方式, 例如生命周期、每次使用确认或扩展约束. 如果 agent 不理解某个必需约束, 应拒绝添加该 key, 而不是忽略约束后继续保存. 这样可以保证调用方设定的安全策略不会在 agent 内被静默放宽.