keyring 19.1.0

安装和使用python keyring lib

目录

• 安装和使用python keyring lib
• 什么是python keyring lib？
• 安装说明
• Linux系统

使用钥匙圈

命令行实用程序

配置您的keyring库

根据配置文件定制密钥环

配置文件路径

配置文件内容

第三方后端

编写自己的keyring后端

在运行时设置keyring"id="id13" rel="nofollow">在运行时设置keyring

在ubuntu 16.04上使用keyring

在无头Linux系统上使用keyring"id="id15" rel="nofollow">在无头Linux系统上使用keyring

将keyring lib与应用程序集成"id="id16" rel="nofollow">将keyring lib与应用程序集成

• api接口
• 异常

参与

• 安全联系人
• 制作发行版
• 运行测试
• 使用tox

背景

什么是python keyring lib？

python keyring lib提供了一种访问系统keyring服务的简单方法 来自python。它可以用于任何需要安全密码存储的应用程序。

keyring库在mit许可证和psf许可证下都有许可证。

python keyring库支持这些推荐的keyring后端：

• MacOS的钥匙链
• freedesktop 特勤处 支持许多de，包括 gnome（需要 secretstorage ）
• kde4&kde5 kwallet （需要 dbus ）
• Windows凭据锁

其他keyring实现可通过第三方后端获得。

安装说明

从索引安装

使用您喜爱的安装程序安装。例如：

< Buff行情> $pip安装钥匙圈

Linux系统

在linux上，kwallet后端依赖于dbus python，它并不总是依赖于dbus python 使用pip时正确安装（需要编译）。所以我们建议 dbus python是作为系统包安装的。同样适用于 python 2下的秘密存储后端（python 3下的另一个d-bus 使用实现）。

使用钥匙圈

keyring的基本用法非常简单：只需调用keyring.set撸password 和钥匙圈。获取密码：

< Buff行情>

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

命令行实用程序

keyring提供一个 keyring 命令，该命令与 包裹。在大多数环境中安装钥匙圈后， 命令应可用于设置、获取和删除 密码。有关用法的详细信息，请在不带参数的情况下调用 或者使用 --help

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

命令行功能也作为可执行文件公开 包，适合从python调用，如so:

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

配置您的密钥环库

python keyring lib包含几个backen的实现DS。这个 图书馆意志 自动选择最适合您当前使用的钥匙圈 环境。您还可以指定要在 配置文件或通过调用 set_keyring（） 函数。

按配置文件自定义密钥环

本节介绍如何更改配置文件中的选项。

配置文件路径

lib的配置存储在一个名为"keyringrc.cfg"的文件中。这个 必须在平台特定位置找到文件。确定 在存储配置文件的位置，运行以下命令：

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

一些keyring还将keyring数据存储在文件系统中。确定 在存储数据文件的位置，运行以下命令：

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

配置文件内容

要指定keyring后端，请将默认keyring选项设置为 该后端类的完整路径，例如 钥匙圈.backends.os_x.keyring

如果指示了keyring path，keyring会将该路径添加到python中 加载后端之前的模块搜索路径。

例如，此配置可用于加载 simplekeyring 来自 /demo 目录（未实现）：

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

第三方后端

除了核心钥匙圈包提供的后端外 最常见和最安全的用例 其他的keyring后端实现是否可用于 用例。只需安装它们即可使用：

• 密钥环.cryptfile -加密文本文件存储。
• 键环_jeepney -a 纯python后端，使用用于桌面的特勤局dbus api Linux .
• 密钥环.alt -"备用"， 可能是不安全的后端，最初是核心包的一部分，但是 可选择加入。
• gsheet钥匙圈 -在谷歌工作表中存储秘密的后端。供使用 ipython机密
• bitwarden密钥环 -在Bitwarden中存储机密的后端 密码管理器。

编写自己的keyring后端

后端的接口由keyring.backend.keyringbackend定义。 每个后端都应该从该基类派生并定义优先级。 属性和三个函数： get_password（） ， set_password（） ，以及 删除密码（） 。如果 期望的

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

keyring使用入口点来允许任何第三方包实现 无需对键环本身进行任何修改的后端。感兴趣的人 鼓励创建新的后端以创建新的第三方包 在 keyrings 名称空间中，以 keyrings.alt建模的方式 包装 。参见 setup.py 文件 在该项目中获取有关如何创建必需入口点的提示。 证明必要的后端可考虑包含在核心中 库，尽管安装这些第三方包很容易S应该 意味着扩展可能随时可用。

如果您已经为keyring创建了扩展，请向 请将您的分机作为可用分机提出。

在运行时设置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 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, password):
        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"))

在ubuntu 16.04上使用keyring

以下是在 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

可以在Linux系统上使用secretservice后端 X11服务器可用（仅需要D总线）。要做到这一点，你需要 以下内容：

• 安装gnome keyring守护进程。

• 启动一个d-bus会话，例如运行dbus运行会话并运行 该外壳中包含以下命令。

• 使用 unlock选项运行 gnome keyring守护进程。描述 这个选项显示：

  < Buff行情>

  从stdin读取一个密码，并使用它来解锁登录密钥环 如果登录密钥环不存在，则创建它。

  启动该命令时，将密码输入stdin并 按CTRL+D（数据结束）。在那之后，守护进程将进入 背景（使用 --前景选项来防止这种情况发生）。

• 现在您可以使用keyring的secretservice后端。记住 在与守护进程相同的d-bus会话中运行应用程序。

将keyring lib集成到应用程序中

API接口

keyring库有几个功能：

• get_keyring（） ：返回当前加载的keyring实现。
• 获取密码（服务，用户名） ：返回存储在 主动钥匙圈。如果密码不存在，则返回"无"。
• 获取凭据（服务，用户名） ：返回存储的凭据对象 在活动钥匙圈中。此对象至少包含 用户名 和 指定服务的密码属性，其中返回 用户名 可能与参数不同。
• 设置密码（服务、用户名、密码） ：将密码存储在 钥匙圈。
• 删除密码（服务，用户名） ：删除存储在 钥匙圈。如果密码不存在，将引发异常。

在所有情况下，参数（ 服务 ， 用户名 ， 密码 ） 应该是Unicode文本。在python 2上，这些参数被接受为 默认编码中的简单str 解码成文本。有些后端可能接受这些参数的 字节 ， 但这种用法是不可取的。

异常情况

keyring库引发以下异常：

• keyring.errors.keyring error ：keyring库中所有异常的基本错误类。
• keyring.errors.initerror ：无法初始化keyring时引发。
• keyring.errors.passwordseterror ：在输入密码时引发无法在钥匙圈中设置。
• keyring.errors.passworddeleteerror ：当无法在keyring中删除密码时引发。

参与进来

python keyring lib是一个开放的社区项目，非常欢迎新的 贡献者。

• 存储库： https://github.com/jaraco/keyring/
• bug跟踪器： https://github.com/jaraco/keyring/issues/
• 邮件列表：http://groups.google.com/group/python-keyring" rel="nofollow">http://groups.google.com/group/python keyring

安全联系人

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

制作发行版

这个项目通过travis ci使用自动发布。这个 简单的工作流是标记提交并将其推送到github。如果它 通过对最新python版本的测试，它将自动 部署到PYPI。

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

< Buff行情>

• 首先确保测试通过（最好在Windows和Linux上）
• 检查更改日志是否为预期版本的当前日志

运行测试

测试是 连续运行 使用 特拉维斯ci.

要自己运行测试，您需要将keyring安装到某些环境中 可以测试的。下面介绍推荐的技术。

使用tox

keyring更喜欢使用 tox 来运行测试。 只需安装并调用 tox

这是travis ci脚本使用的技术。

背景

该项目基于塔雷克·齐亚德在本文中的想法。张康 最初是作为a 谷歌代码之夏项目和tarek执行的。 在这个项目上指导Kang。