护套 🔏

护套提供了一种基于密码学强度的无服务器密钥管理基础设施。护套支持将密钥以代码的形式进行管理，安全地以可版本化的格式存储密钥，与相应的应用程序代码并存。

护套的方法让您

• 利用现有的用户、版本控制和备份系统，无需设置任何基础设施
• 支持多个环境
• 易于与现有的密钥管理系统集成（AWS/Heroku/TravisCI）

护套还有

• 最小化团队需要记住和保护的密码短语和密钥的数量
• 大大优于硬编码的明文密钥！

安装

目前，在所有平台上安装护套最简单的方法是使用pip

pip install pocket_protector

这将安装命令行应用程序pocket_protector，方便地简写为pprotect，您可以使用它来测试您的安装

$ pprotect version
pocket_protector version 18.0.1

一旦上述操作成功，我们就可以开始使用护套了！

用法

护套旨在尽可能易于使用。尽管如此，理解安全性需要时间，因此请确保阅读以下快速入门和参考，并阅读我们的用户指南。

快速入门

口袋保护器的命令行界面是其主要接口。它提供了一套紧凑的命令，每个命令代表你可能在秘密存储上执行的一个操作。基本用法从你的笔记本电脑、已签出的代码仓库开始。

# create a new protected file
pprotect init

# add a key domain
pprotect add-domain

# add a secret to the new key domain
pprotect add-secret

# decrypt and read out the secret
pprotect decrypt-domain

这些命令在必要时都会提示用户输入凭证。请参阅下文关于传递凭证的部分。

当你完成秘密存储的更新后，只需使用git commit（或等效命令）保存你的更改。如果你犯了任何错误，可以使用你的版本控制系统来回滚更改。

传递凭证

默认情况下，当需要时，pocket_protector命令会提示你输入凭证。但便利性和自动化都要求有更多的选项，如下所示

• 命令行标志

  • -u / --user USER_EMAIL - 指定需要它的子命令的用户电子邮件
  • --passphrase-file PATH - 指定包含密码的可读文件的路径（适用于基于挂载的密钥管理，如Docker）
  • --domain DOMAIN - 指定域名
  • --non-interactive - 当无法通过其他方式获取凭证时，导致命令失败

• 环境变量

  • PPROTECT_USER - 包含用户电子邮件的环境变量
  • PPROTECT_PASSPHRASE - 包含密码的环境变量（适用于基于环境变量的密钥管理，由AWS/Heroku/许多CI系统使用）

在任何情况下，标志都优于环境变量，并且两者都优于并绕过交互式提示。如果传递了错误的凭证，pocket_protector不会自动检查其他来源。

请参阅我们的用户指南以获取更多信息。

命令摘要

以下是所有命令的摘要

usage: pprotect [COMMANDS]

Commands:
  add-domain            add a new domain to the protected
  add-key-custodian     add a new key custodian to the protected
  add-owner             add a key custodian as owner of a domain
  add-secret            add a secret to a specified domain
  decrypt-domain        decrypt and display JSON-formatted cleartext for a
                        domain
  init                  create a new pocket-protected file
  list-all-secrets      display all secrets, with a list of domains the key is
                        present in
  list-audit-log        display a chronological list of audit log entries
                        representing file activity
  list-domain-secrets   display a list of secrets under a specific domain
  list-domains          display a list of available domains
  list-user-secrets     similar to list-all-secrets, but filtered by a given
                        user
  rm-domain             remove a domain from the protected
  rm-owner              remove an owner's privileges on a specified domain
  rm-secret             remove a secret from a specified domain
  rotate-domain-keys    rotate the internal keys for a particular domain (must
                        be owner)
  set-key-custodian-passphrase
                        change a key custodian passphrase
  update-secret         update an existing secret in a specified domain

设计

操作原理是protected.yaml文件由根级别的"密钥域"组成。每个域存储由密钥对加密的数据。密钥对中的公钥以明文形式存储，以便任何人都可以加密并添加新的秘密。私钥由所有者的密码加密。所有者被称为"密钥保管人"，他们的私钥由密码保护。

出于不同的安全目的，秘密被分成不同的域。例如，prod、dev和stage可能都是不同的域。受保护的存储可以拥有团队和应用程序所需的最少或最多的域。

为了允许在特定环境中访问秘密，必须使用用户和密码调用Pocket Protector。只要凭证正确并且用户有权访问域，该域内的所有秘密都将解锁。

密码的安全性将取决于域。例如，用于本地开发的域可能将密码设置为环境变量，或在配置文件中硬编码它。

另一方面，生产域可能需要手动输入授权发布工程师，或使用AWS/GCP/Heroku密钥管理解决方案注入密码。

对于生产域，使用AWS / Heroku密钥管理来存储密码

应用程序/脚本想要获取其秘密

# at initialization
secrets = KeyFile.decrypt_domain(domain_name, Creds(name, passphrase))
# ... later to access a secret
secrets[secret_name]

想要添加/覆盖秘密的应用程序/脚本

KeyFile.from_file(path).with_secret(
    domain_name, secret_name, value).write()

注意 -- 读取秘密需要安全环境密钥，但写入不需要。秘密的变更管理旨在遵循正常的源代码管理。

文件结构

[key-domain]:
  meta:
    owners:
      [name]: [encrypted-private-key]
    public_key: [b64-bytes]
    private_key: [b64-bytes]
  secret-[name]: [b64-bytes]
key-custodians:
  [name]:
    public-key: [b64-bytes]
    encrypted-private-key: [b64-bytes]

威胁模型

攻击者被认为能够读取但不能写入protected.yaml的内容。这可能是因为开发者的笔记本电脑被入侵，GitHub凭证被泄露，或者（最有可能的是）Git历史记录意外地推送到公开可访问的仓库。

有了读取权限，攻击者可以获得环境和秘密名称，以及哪些秘密用于哪些环境。

由于安全模型假设攻击者没有写入权限，因此整个文件或条目都没有签名。

备注

口袋保护器是一个精简的以人为中心的秘密管理系统，专门为与分布式版本控制系统协同工作而定制。

• 口袋保护器是一种数据保护工具，而不是变更管理工具。虽然它具有方便的功能，例如非正式的 audit_log，但口袋保护器旨在与您的版本管理工具一起使用。已签名的提交是一个特别好的补充。
• 口袋保护器是为单用户使用的。这与其说是扩展限制，不如说是扩展特性。单用户意味着每个 pprotect 命令最多需要一个认证用户。不需要旁路通信，从而最小化泄露，同时保持与版本管理一样分布式的系统。

常见问题解答

保护写入权限

按照设计，口袋保护器不提供对 protected.yaml 文件未授权写入的安全措施。首先，由于没有任何公钥基础设施，口袋保护器不是加密签名的良好基础。（修改文件的攻击者还可以用自己的密钥对替换签名密钥对；检测这种行为的唯一方法是在文件之外有一个数据存储。）

其次——更重要的是——Git 或 Mercurial 仓库已经对写入权限有很好的控制。所有更改都是可审计的，使用 ssh 密钥对或用户密码进行认证。为了进一步的安全，请考虑使用已签名的提交。

• https://git-scm.cn/book/id/v2/Git-Tools-Signing-Your-Work
• https://help.github.com/articles/signing-commits-using-gpg/
• https://docs.gitlab.com/ee/user/project/repository/gpg_signed_commits/index.html