keyring 23.9.3

安装 - Linux

在 Linux 上，KWallet 后端依赖于dbus-python，在使用 pip 时并不总是正确安装（需要编译）。为获得最佳效果，请将 dbus-python 作为系统包安装。

兼容性 - macOS

macOS 钥匙串支持 macOS 11 (Big Sur) 和更高版本需要 Python 3.8.7 或更高版本以及“universal2”二进制文件。有关详细信息，请参阅 #525。

使用密钥环

密钥环的基本用法非常简单：只需调用 keyring.set_password和keyring.get_password：

>>> import keyring
>>> keyring.set_password("system", "username", "password")
>>> keyring.get_password("system", "username")
'password'

$ keyring --help
$ keyring set system username
Password for 'username' in 'system':
$ keyring get system username
password

$ python -m keyring --help
$ python -m keyring set system username
Password for 'username' in 'system':
$ python -m keyring get system username
password

配置

python 密钥环库包含多个后端的实现。该库将尝试自动选择最适合当前环境的后端。用户还可以在配置文件中或通过调用set_keyring()函数指定首选密钥环。

python -c "import keyring.util.platform_; print(keyring.util.platform_.config_root())"

python -c "import keyring.util.platform_; print(keyring.util.platform_.data_root())"

[backend]
default-keyring=simplekeyring.SimpleKeyring
keyring-path=demo

第三方后端

除了核心密钥环包为最常见和最安全的用例提供的后端之外，还有其他可用于其他用例的密钥环后端实现。只需安装它们即可使它们可用：

• keyrings.cryptfile - 加密文本文件存储。

• keyring_jeepney - 一个纯 Python 后端，使用桌面 Linux 的秘密服务 DBus API。

• keyrings.alt - “替代”，可能不安全的后端，最初是核心包的一部分，但可用于选择加入。

• gsheet-keyring - 在 Google Sheet 中存储秘密的后端。与 ipython-secrets一起使用。

• bitwarden-keyring - 在BitWarden 密码管理器 中存储秘密的后端。

• sagecipher - 一个加密后端，它使用 ssh 代理协议的签名操作来派生密码密钥。

• keyrings.osx_keychain_keys - OSX 钥匙串密钥管理，用于私有、公共和对称密钥。

编写自己的密钥环后端

后端接口由keyring.backend.KeyringBackend定义。每个后端都应该从该基类派生并定义一个优先级 属性和三个函数：get_password()、set_password()和 delete_password()。如果需要，可以定义get_credential()函数。

有关此类接口的更多详细信息，请参见后端模块。

Keyring 使用入口点来允许任何第三方包实现后端，而无需对密钥环本身进行任何修改。鼓励那些对创建新后端感兴趣的人在keyrings命名空间中创建新的第三方包，其方式由keyrings.alt 包建模。有关如何创建必要入口点的提示，请参阅该 项目中的setup.cfg文件。可以考虑将被证明必不可少的后端包含在核心库中，尽管安装这些第三方包的便利性应该意味着扩展可能很容易获得。

要为 Keyring 创建扩展，请提交拉取请求以将您的扩展作为可用扩展提及。

运行时配置

Keyring 还允许调用 api set_keyring()对后端进行编程配置。指定的后端随后将用于存储和检索密码。

调用set_keyring：

# define a new keyring class which extends the KeyringBackend
import keyring.backend

class TestKeyring(keyring.backend.KeyringBackend):
    """A test keyring which always outputs the same password
    """
    priority = 1

    def set_password(self, servicename, username, password):
        pass

    def get_password(self, servicename, username):
        return "password from TestKeyring"

    def delete_password(self, servicename, username):
        pass

# set the keyring for keyring lib
keyring.set_keyring(TestKeyring())

# invoke the keyring lib
try:
    keyring.set_password("demo-service", "tarek", "passexample")
    print("password stored successfully")
except keyring.errors.PasswordSetError:
    print("failed to store password")
print("password", keyring.get_password("demo-service", "tarek"))

禁用密钥环

在许多情况下，永远不需要卸载密钥环。特别是在 Windows 和 macOS 上，keyring 的行为通常是退化的，这意味着它将向调用者返回空值，从而允许调用者回退到其他一些行为。

在某些情况下，密钥环的默认行为是不可取的，最好完全禁用密钥环行为。有几种机制可以禁用密钥环：

• 卸载密钥环。大多数应用程序都可以容忍未安装密钥环。卸载密钥环应该会导致这些应用程序回退到没有密钥环的行为。这种方法会影响安装密钥环的 Python 环境。

• 在环境中配置 Null 密钥环。 在环境中设置 PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring ，将使用Null（退化）后端。这种方法会影响设置该变量的 Keyring 的所有使用。

• 通过运行keyring --disable或python -m keyring --disable为用户永久配置 Null 密钥环 。这种方法会影响该用户对密钥环的所有使用。

改变密钥环行为

Keyring 提供了一种通过环境变量改变 keyring 行为的机制。每个后端都实现一个 KeyringBackend.set_properties_from_env，当调用它时，它将找到所有以 KEYRING_PROPERTY_{NAME}开头的环境变量，并为密钥环上的每个 {NAME.lower()}设置一个属性。在初始化默认/配置的密钥环期间调用此方法。

此机制可用于在各种密钥环上设置一些有用的值，包括：

• 钥匙链; macOS，备用钥匙串文件的路径

• 应用程序；Linux/SecretService，应用程序的备用 ID

在 Ubuntu 16.04 上使用密钥环

以下是在 Ubuntu 16.04 的虚拟环境中安装密钥环的完整脚本。没有使用配置文件：

$ sudo apt install python3-venv libdbus-glib-1-dev
$ cd /tmp
$ pyvenv py3
$ source py3/bin/activate
$ pip install -U pip
$ pip install secretstorage dbus-python
$ pip install keyring
$ python
>>> import keyring
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring object at 0x7f9b9c971ba8>
>>> keyring.set_password("system", "username", "password")
>>> keyring.get_password("system", "username")
'password'

在无头 Linux 系统上使用 Keyring

可以在没有 X11 服务器的 Linux 系统上使用 SecretService 后端（仅需要 D-Bus）。在这种情况下：

• 安装GNOME 密钥环守护程序。

• 启动一个 D-Bus 会话，例如运行dbus-run-session -- sh并在该 shell 中运行以下命令。

• 使用--unlock选项运行gnome-keyring-daemon 。该选项的描述说：

  从标准输入读取密码，并使用它来解锁登录密钥环，或者如果登录密钥环不存在则创建它。

  启动该命令后，在标准输入中输入密码并按 Ctrl+D（数据结束）。之后，守护进程将分叉到后台（使用--foreground选项阻止）。

• 现在您可以使用 Keyring 的 SecretService 后端了。请记住在与守护进程相同的 D-Bus 会话中运行您的应用程序。

在 Docker 容器中的无头 Linux 系统上使用 Keyring

也可以在 Docker 容器中将密钥环与 SecretService 后端一起使用。您需要做的就是安装必要的依赖项并添加–privileged标志以避免在尝试解锁系统的密钥环时出现任何Operation not allowed 错误。

以下是在 Ubuntu 18:04 容器上安装密钥环的完整记录：

docker run -it -d --privileged ubuntu:18.04

$ apt-get update
$ apt install -y gnome-keyring python3-venv python3-dev
$ python3 -m venv venv
$ source venv/bin/activate # source a virtual environment to avoid polluting your system
$ pip3 install --upgrade pip
$ pip3 install keyring
$ dbus-run-session -- sh # this will drop you into a new D-bus shell
$ echo 'somecredstorepass' | gnome-keyring-daemon --unlock # unlock the system's keyring

$ python
>>> import keyring
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring object at 0x7f9b9c971ba8>
>>> keyring.set_password("system", "username", "password")
>>> keyring.get_password("system", "username")
'password'

一体化

参与其中

Python keyring lib 是一个开放的社区项目，热切欢迎贡献者。

• 存储库：https ://github.com/jaraco/keyring/

• 错误跟踪器：https ://github.com/jaraco/keyring/issues/

• 邮件列表：http ://groups.google.com/group/python-keyring

对于企业

作为 Tidelift 订阅的一部分提供。

该项目和其他数千个软件包的维护者正在与 Tidelift 合作，提供一个涵盖您使用的所有开源的企业订阅。

了解更多。

安全联系人

要报告安全漏洞，请使用 Tidelift 安全联系人。Tidelift 将协调修复和披露。

安全注意事项

在使用这个库之前，每个内置后端都可能需要了解安全注意事项。鼓励使用密钥环的工具或库的作者 考虑这些问题。

与任何已知安全问题列表一样，此列表并不详尽。可以根据需要添加其他问题。

• macOS 钥匙串

  • 任何 Python 脚本或应用程序都可以从同一个 Python 可执行文件访问由密钥环创建的机密 ，而无需操作系统提示用户输入密码。要使任何特定机密在每次访问时都提示输入密码，请使用钥匙串访问应用程序找到凭据，然后在访问控制设置中，从允许的应用程序列表中删除Python。

• Freedesktop 特勤局

  • 未进行任何分析

• KDE4 & KDE5 KWallet

  • 未进行任何分析

• Windows 凭据储物柜

  • 未进行任何分析

发布版本

该项目利用了自动发布和持续集成。简单的工作流程是标记提交并将其推送到 Github。如果它通过 CI 中的测试，它将自动部署到 PyPI。

发布时要考虑的其他事项：

• 检查更新日志是否是预期版本的最新版本。

运行测试

测试在 Github Actions 中持续运行。

要在本地运行测试，请安装并调用 tox。

背景

该项目基于 Tarek Ziade 在这篇文章中的想法。Kang Zhang 最初将其作为Google Summer of Code项目进行，Tarek 在此项目上指导 Kang。