安全地存储和访问您的密码。
项目描述
Python 密钥环库提供了一种从 python 访问系统密钥环服务的简单方法。它可用于任何需要安全密码存储的应用程序。
支持这些推荐的密钥环后端:
macOS钥匙串
Freedesktop Secret Service支持许多 DE,包括 GNOME(需要secretstorage)
其他密钥环实现可通过第三方后端获得。
安装 - 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 提供了一个随包一起安装的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
配置
python 密钥环库包含多个后端的实现。该库将尝试自动选择最适合当前环境的后端。用户还可以在配置文件中或通过调用set_keyring()函数指定首选密钥环。
配置文件路径
配置存储在一个名为“keyringrc.cfg”的文件中,该文件位于特定于平台的位置。要确定配置文件的存储位置,请运行以下命令:
python -c "import keyring.util.platform_; print(keyring.util.platform_.config_root())"
一些密钥环还将密钥环数据存储在文件系统中。要确定数据文件的存储位置,请运行:
python -c "import keyring.util.platform_; print(keyring.util.platform_.data_root())"
配置文件内容
要指定密钥环后端,请将default-keyring选项设置为该后端的类的完整路径,例如 keyring.backends.OS_X.Keyring。
如果指定了keyring-path,keyring 会在加载后端之前将该路径添加到 Python 模块搜索路径。
例如,此配置可能用于 从./demo目录中的simplekeyring模块加载SimpleKeyring(未实现):
[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'
一体化
API
密钥环库有几个功能:
get_keyring():返回当前加载的密钥环实现。
get_password(service, username):返回存储在活动密钥环中的密码。如果密码不存在,则返回 None。
get_credential(service, username):返回存储在活动密钥环中的凭证对象。该对象至少包含指定服务的 用户名和 密码属性,其中返回的用户名可能与参数不同。
set_password(service, username, password):将密码存储在密钥环中。
delete_password(service, username):删除密钥环中存储的密码。如果密码不存在,则会引发异常。
在所有情况下,参数(服务、用户名、密码)都应该是 Unicode 文本。
例外
密钥环库引发以下异常:
keyring.errors.KeyringError:密钥环库中所有异常的基本错误类。
keyring.errors.InitError:无法初始化密钥环时引发。
keyring.errors.PasswordSetError:无法在密钥环中设置密码时引发。
keyring.errors.PasswordDeleteError:在密钥环中无法删除密码时引发。
参与其中
Python keyring lib 是一个开放的社区项目,热切欢迎贡献者。
对于企业
作为 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。