安全存储和访问您的密码。
项目描述
Python keyring库提供了一个简单的方法从Python访问系统密钥环服务。它可以用于任何需要安全密码存储的应用程序。
以下推荐的密钥环后端得到支持
macOS Keychain
Freedesktop Secret Service 支持许多桌面环境，包括GNOME（需要 secretstorage）
其他密钥环实现可通过 第三方后端 获取。
安装 - Linux
在Linux上，KWallet后端依赖于 dbus-python，当使用pip时（需要编译），它并不总是正确安装。为了获得最佳效果，请将dbus-python安装为系统包。
兼容性 - macOS
macOS密钥链支持macOS 11（Big Sur）及更高版本，需要Python 3.8.7或更高版本以及“universal2”二进制文件。有关详细信息，请参阅 #525。
使用Keyring
keyring的基本用法非常简单：只需调用 keyring.set_password 和 keyring.get_password
>>> 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调用：
$ python -m keyring --help $ python -m keyring set system username Password for 'username' in 'system': $ python -m keyring get system username password
Tab自动补全
如果通过包管理器（apt、pacman、nix、homebrew等）安装，这些shell补全可能已经与包一起分发（无需采取行动）。
如果安装了 completion 扩展，密钥环提供Tab自动补全功能。
$ pip install 'keyring[completion]'
然后，生成shell补全，例如
$ keyring --print-completion bash | sudo tee /usr/share/bash-completion/completions/keyring $ keyring --print-completion zsh | sudo tee /usr/share/zsh/site-functions/_keyring $ keyring --print-completion tcsh | sudo tee /etc/profile.d/keyring.csh
注意： /usr/share 路径主要用于GNU/Linux。对于其他操作系统，请考虑以下选项：
macOS（Homebrew x86）：/usr/local/share
macOS（Homebrew ARM）：/opt/homebrew/share
Android（Termux）：/data/data/com.termux/files/usr/share
Windows（mingw64 of msys2）：/mingw64/share
…
在安装shell补全后，根据您的shell推荐的说明启用它们。例如：
bash：安装 bash-completion，并确保 . /usr/share/bash-completion/bash_completion 在 ~/.bashrc 中。
zsh：确保 autoload -Uz compinit && compinit 出现在 ~/.zshrc 中，然后 grep -w keyring ~/.zcompdump 以验证keyring是否存在，表示它已正确安装。
配置
python keyring库包含对几个后端的实现。库将尝试自动为当前环境选择最合适的后端。用户也可以通过配置文件或调用 set_keyring() 函数指定首选密钥环。
配置文件路径
配置存储在名为“keyringrc.cfg”的文件中，该文件位于特定于平台的存储位置。要确定配置文件的存储位置，请运行 keyring diagnose。
配置文件内容
要指定密钥环后端，将 default-keyring 选项设置为该后端类的完整路径，例如 keyring.backends.macOS.Keyring。
如果指定了 keyring-path，密钥环将在加载后端之前将该路径添加到Python模块搜索路径。
例如，此配置可能用于从 ./demo 目录中的 simplekeyring 模块加载 SimpleKeyring（未实现）。
[backend] default-keyring=simplekeyring.SimpleKeyring keyring-path=demo
第三方后端
除了核心密钥环包提供的后端，用于最常见和安全用例外，还有其他用例的密钥环后端实现。只需安装它们即可使其可用。
keyrings.cryptfile - 加密文本文件存储。
keyrings.alt - “备用”，可能不安全的后端，最初是核心包的一部分，但现在可供选择。
gsheet-keyring - 将机密存储在Google表格中的后端。与 ipython-secrets 一起使用。
bitwarden-keyring - 将机密存储在 BitWarden 密码管理器中的后端。
onepassword-keyring - 将机密存储在 1Password 密码管理器中的后端。
sagecipher - 使用ssh代理协议的签名操作来派生加密密钥的加密后端。
keyrings.osx_keychain_keys - 用于私钥、公钥和对称密钥的OSX密钥链密钥管理。
- keyring_pass.PasswordStoreBackend
Python的keyring密码存储后端
keyring_jeepney - 使用桌面Linux的secret service DBus API的纯Python后端（需要 keyring<24）。
编写自己的密钥环后端
后端接口由 keyring.backend.KeyringBackend 定义。每个后端都应该从该基类派生，并定义一个 priority 属性和三个函数： get_password()、set_password() 和 delete_password()。如果需要，还可以定义 get_credential() 函数。
请参阅 backend 模块以了解该类接口的更多详细信息。
Keyring使用入口点来允许任何第三方包在不修改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"))
禁用Keyring
在许多情况下，卸载keyring永远不会是必要的。特别是在Windows和macOS上，keyring的行为通常是退化的，这意味着它将向调用者返回空值，允许调用者回退到其他行为。
在某些情况下，keyring的默认行为可能是不受欢迎的，最好是完全禁用keyring行为。有多种机制可以禁用keyring
卸载keyring。大多数应用程序可以容忍keyring未安装。卸载keyring应导致这些应用程序回退到没有keyring的行为。此方法会影响keyring可能已安装的Python环境。
在环境中配置Null密钥环。设置 PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring，并将使用 Null（退化的）后端。此方法会影响设置该变量的所有Keyring使用。
通过运行 keyring --disable 或 python -m keyring --disable 永久为用户配置Null密钥环。此方法会影响该用户的所有keyring使用。
修改Keyring行为
Keyring提供了一种通过环境变量修改keyring行为的机制。每个后端实现了一个 KeyringBackend.set_properties_from_env，当调用时，将查找以 KEYRING_PROPERTY_{NAME} 开头的所有环境变量，并将为每个 {NAME.lower()} 在keyring上设置一个属性。此方法在默认/配置的keyring初始化期间被调用。
此机制可用于在各个密钥环上设置一些有用的值，包括
keychain; macOS，到备用密钥链文件的路径
appid；Linux/SecretService，应用程序的备用ID
在Ubuntu 16.04上使用Keyring
以下是在Ubuntu 16.04虚拟环境中安装keyring的完整记录。没有使用配置文件。
$ 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系统上（没有X11服务器可用）也可以使用SecretService后端（只需要D-Bus）。在这种情况下
安装GNOME Keyring守护进程。
启动一个D-Bus会话，例如运行dbus-run-session -- sh，并在该shell中运行以下命令。
使用gnome-keyring-daemon命令并带有--unlock选项。该选项的描述说明
从stdin读取密码，并使用它来解锁登录密钥环或创建它（如果登录密钥环不存在）。
启动该命令后，在stdin中输入密码，然后按Ctrl+D（数据结束）。之后，守护进程将进入后台（使用--foreground选项来阻塞）。
现在您可以使用Keyring的SecretService后端。请记住，在同一个D-Bus会话中运行您的应用程序，与守护进程相同。
在Docker容器中使用无头Linux系统上的Keyring
您还可以在Docker容器中使用带有SecretService后端的keyring。您需要做的只是安装必要的依赖项，并将–privileged标志添加到其中，以避免在尝试解锁系统密钥环时出现任何Operation not permitted错误。
以下是安装keyring在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'
集成
API
keyring库有几个函数
get_keyring()：返回当前加载的密钥环实现。
get_password(service, username)：返回存储在活动密钥环中的密码。如果密码不存在，则返回None。
get_credential(service, username)：返回存储在活动密钥环中的凭证对象。该对象至少包含username和password属性，对于指定的服务，返回的username可能不同于参数。
set_password(service, username, password)：将密码存储在密钥环中。
delete_password(service, username)：删除密钥环中存储的密码。如果密码不存在，将引发异常。
在所有情况下，参数（service、username、password）应该是Unicode文本。
异常
keyring库引发以下异常
keyring.errors.KeyringError：keyring库中所有异常的基类。
keyring.errors.InitError：当密钥环无法初始化时引发。
keyring.errors.PasswordSetError：当无法在密钥环中设置密码时引发。
keyring.errors.PasswordDeleteError：当无法在密钥环中删除密码时引发。
参与其中
Python keyring库是一个开放的社区项目，热切欢迎贡献者。
安全考虑
在使用此库之前，每个内置后端可能都有需要了解的安全考虑因素。鼓励使用 keyring 的工具或库的作者考虑这些关注点。
与任何已知安全问题的列表一样，此列表不是详尽的。可以根据需要添加额外的问题。
- macOS密钥链
任何Python脚本或应用程序都可以访问由 keyring 创建的秘密，而无需操作系统提示用户输入密码。要使任何特定秘密在每次访问时都提示输入密码，请使用 Keychain Access 应用程序查找凭证，然后在 访问控制 设置中从允许的应用程序列表中移除 Python。
- Freedesktop秘密服务
尚未进行分析
- KDE4 & KDE5 KWallet
尚未进行分析
- Windows凭证存储库
尚未进行分析
制作发布版本
本项目利用自动发布和持续集成。简单的流程是标记提交并将其推送到GitHub。如果它通过CI中的测试，它将被自动部署到PyPI。
发布时需要考虑的其他事项
请确保变更日志适用于预期的发布版本。
运行测试
测试在GitHub Actions中持续运行。
要在本地运行测试，请安装并调用 tox。
背景
本项目基于Tarek Ziade在此帖子中的想法。Kang Zhang最初将其作为Google Summer of Code项目实施，Tarek在该项目中指导Kang。
企业版
作为Tidelift订阅的一部分提供。
本项目以及成千上万的其它包的维护者正在与Tidelift合作，提供一项企业订阅，涵盖您使用的所有开源软件。
了解更多.
下载文件
下载适用于您平台的文件。如果您不确定选择哪一个，请了解有关安装包的更多信息。
源代码分发
编译分发
keyring-25.4.1.tar.gz的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | b07ebc55f3e8ed86ac81dd31ef14e81ace9dd9c3d4b5d77a6e9a2016d0d71a1b |
|
| MD5 | 18421ba10fcf6af96586aa0761cc667d |
|
| BLAKE2b-256 | a51c2bdbcfd5d59dc6274ffb175bc29aa07ecbfab196830e0cfbde7bd861a2ea |
keyring-25.4.1-py3-none-any.whl的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 5426f817cf7f6f007ba5ec722b1bcad95a75b27d780343772ad76b17cb47b0bf |
|
| MD5 | ef5cf00ede2a18c500438cb8a94b6d62 |
|
| BLAKE2b-256 | 8325e6d59e5f0a0508d0dca8bb98c7f7fd3772fc943ac3f53d5ab18a218d32c0 |
