keyring
v25.5.0
Библиотека ключей Python предоставляет простой способ доступа к системной службе ключей из Python. Его можно использовать в любом приложении, которому требуется безопасное хранение паролей.
Поддерживаются следующие рекомендуемые серверные программы для ключей:
Другие реализации связки ключей доступны через сторонние бэкенды.
В Linux серверная часть KWallet использует dbus-python, который не всегда устанавливается правильно при использовании pip (требуется компиляция). Для достижения наилучших результатов установите dbus-python как системный пакет.
Связка ключей macOS поддерживает macOS 11 (Big Sur) и более поздние версии, требующие Python 3.8.7 или более поздней версии с двоичным файлом «universal2». Подробности см. в № 525.
Базовое использование keyring довольно просто: просто вызовите keyring.set_password и keyring.get_password :
>>> импортировать брелок
>>> keyring.set_password("система", "имя пользователя", "пароль")
>>> keyring.get_password("система", "имя пользователя")
'пароль'
Keyring предоставляет команду keyring , которая устанавливается вместе с пакетом. После установки набора ключей в большинстве сред должна быть доступна команда для установки, получения и удаления паролей. Для получения дополнительной информации об использовании вызовите без аргументов или с --help следующим образом:
$ брелок --help $ keyring установить системное имя пользователя Пароль для «имя пользователя» в «системе»: $ keyring получить системное имя пользователя пароль
Функциональность командной строки также представлена в виде исполняемого пакета, подходящего для вызова из Python, например:
$ python -m брелок --help $ python -m keyring установить имя пользователя системы Пароль для «имя пользователя» в «системе»: $ python -m keyring получить системное имя пользователя пароль
Если они установлены через менеджер пакетов (apt, pacman, nix, homebrew и т. д.), эти дополнения оболочки могут уже распространяться вместе с пакетом (никаких действий не требуется).
Брелок обеспечивает завершение табуляции, если установлено дополнительное completion :
$ pip install 'брелок[завершение]'
Затем сгенерируйте завершение оболочки, что-то вроде:
$ 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 тройник /etc/profile.d/keyring.csh
Примечание . Путь /usr/share в основном предназначен для GNU/Linux. Для других ОС обратите внимание:
После установки дополнений оболочки включите их, следуя рекомендуемым инструкциям вашей оболочки. например:
. /usr/share/bash-completion/bash_completion в ~/.bashrc .autoload -Uz compinit && compinit появляется в ~/.zshrc , затем grep -w keyring ~/.zcompdump для проверки появления набора ключей, указывающего, что он установлен правильно. Библиотека ключей Python содержит реализации для нескольких бэкэндов. Библиотека попытается автоматически выбрать наиболее подходящую серверную часть для текущей среды. Пользователи также могут указать предпочтительный набор ключей в файле конфигурации или вызвав функцию set_keyring() .
Конфигурация хранится в файле с именем «keyringrc.cfg», расположенном в папке, зависящей от платформы. Чтобы определить, где хранится файл конфигурации, запустите keyring diagnose .
Чтобы указать серверную часть набора ключей, установите для параметра default-keyring полный путь к классу для этого внутреннего интерфейса, например keyring.backends.macOS.Keyring .
Если указан keyring-path , keyring добавит этот путь в путь поиска модуля Python перед загрузкой серверной части.
Например, эту конфигурацию можно использовать для загрузки SimpleKeyring из модуля simplekeyring в каталоге ./demo (не реализовано):
[бэкэнд] default-keyring=simplekeyring.SimpleKeyring keyring-path=демо
В дополнение к бэкэндам, предоставляемым базовым пакетом ключей для наиболее распространенных и безопасных случаев использования, существуют дополнительные реализации бэкендов для ключей, доступные для других случаев использования. Просто установите их, чтобы сделать их доступными:
keyring<24 ). Интерфейс бэкэнда определяется keyring.backend.KeyringBackend . Каждый бэкэнд должен быть производным от этого базового класса и определять атрибут priority и три функции: get_password() , set_password() и delete_password() . При желании можно определить функцию get_credential() .
Более подробную информацию об интерфейсе этого класса см. backend модуле.
Keyring использует точки входа, позволяющие любому стороннему пакету реализовывать серверные части без каких-либо изменений самого набора ключей. Тем, кто заинтересован в создании новых серверных частей, рекомендуется создавать новые сторонние пакеты в пространстве имен keyrings по образцу пакета keyrings.alt. См. файл setup.cfg в этом проекте для получения подсказок о том, как создать необходимые точки входа. Серверные части, которые окажутся необходимыми, могут быть рассмотрены для включения в основную библиотеку, хотя простота установки этих сторонних пакетов должна означать, что расширения могут быть легко доступны.
Чтобы создать расширение для Keyring, отправьте запрос на включение, чтобы ваше расширение было упомянуто как доступное расширение.
Keyring дополнительно позволяет программную настройку серверной части, вызывая API set_keyring() . Указанный бэкэнд впоследствии будет использоваться для хранения и получения паролей.
Чтобы вызвать set_keyring :
# определяем новый класс набора ключей, который расширяет KeyringBackend
импортировать keyring.backend
класс TestKeyring(keyring.backend.KeyringBackend):
"""Тестовый брелок, который всегда выводит один и тот же пароль.
"""
приоритет = 1
def set_password(я, имя службы, имя пользователя, пароль):
проходить
Защиту get_password (я, имя службы, имя пользователя):
вернуть «пароль от TestKeyring»
Защиту delete_password (я, имя службы, имя пользователя):
проходить
# устанавливаем связку ключей для библиотеки ключей
keyring.set_keyring(TestKeyring())
# вызываем библиотеку ключей
пытаться:
keyring.set_password("демо-сервис", "тарек", "passexample")
print("пароль успешно сохранен")
кроме keyring.errors.PasswordSetError:
print("не удалось сохранить пароль")
print("пароль", keyring.get_password("демо-сервис", "тарек"))
Во многих случаях удаление брелока никогда не понадобится. Особенно в Windows и macOS поведение связки ключей обычно вырождается, то есть она возвращает вызывающему объекту пустые значения, позволяя вызывающему объекту вернуться к другому поведению.
В некоторых случаях поведение связки ключей по умолчанию нежелательно, и было бы предпочтительнее вообще отключить поведение связки ключей. Существует несколько механизмов отключения брелока:
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring в среде, и будет использоваться Null (вырожденный) бэкэнд. Этот подход влияет на все виды использования Keyring, где установлена эта переменная.keyring --disable или python -m keyring --disable . Этот подход влияет на все виды использования связки ключей для этого пользователя. Keyring предоставляет механизм изменения поведения связки ключей с помощью переменных среды. Каждый бэкэнд реализует KeyringBackend.set_properties_from_env , который при вызове найдет все переменные среды, начинающиеся с KEYRING_PROPERTY_{NAME} и установит свойство для каждого {NAME.lower()} в связке ключей. Этот метод вызывается во время инициализации набора ключей по умолчанию/настроенного.
Этот механизм можно использовать для установки некоторых полезных значений в различных связках ключей, в том числе:
Ниже приведена полная расшифровка установки брелока в виртуальной среде в Ubuntu 16.04. Конфигурационный файл не использовался:
$ sudo apt install python3-venv libdbus-glib-1-dev
$ компакт-диск /tmp
$ pyvenv py3
$ исходный код py3/bin/активировать
$ пип установить -U пип
$ pip install secretstorage dbus-python
$pip установить брелок
$ питон
>>> импортировать брелок
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring объект по адресу 0x7f9b9c971ba8>
>>> keyring.set_password("система", "имя пользователя", "пароль")
>>> keyring.get_password("система", "имя пользователя")
'пароль'
Бэкэнд SecretService можно использовать в системах Linux без сервера X11 (требуется только D-Bus). В этом случае:
Установите демон GNOME Keyring.
Запустите сеанс D-Bus, например, запустите dbus-run-session -- sh и выполните следующие команды внутри этой оболочки.
Запустите gnome-keyring-daemon с опцией --unlock . В описании этой опции сказано:
Считайте пароль со стандартного ввода и используйте его, чтобы разблокировать связку ключей для входа в систему или создайте ее, если связка ключей для входа не существует.
Когда эта команда запустится, введите пароль в стандартный ввод и нажмите Ctrl+D (конец данных). После этого демон перейдет в фоновый режим (для блокировки используйте параметр --foreground ).
Теперь вы можете использовать серверную часть SecretService Keyring. Не забудьте запустить приложение в том же сеансе D-Bus, что и демон.
Также можно использовать связку ключей с серверной частью SecretService в контейнерах Docker. Все, что вам нужно сделать, это установить необходимые зависимости и добавить флаг --privileged, чтобы избежать ошибок «Операция не разрешена» при попытке разблокировать связку ключей системы.
Ниже приведена полная расшифровка установки брелока в контейнере Ubuntu 18:04:
docker run -it -d --privileged Ubuntu: 18.04
$ apt-get обновление
$ apt install -y gnome-keyring python3-venv python3-dev
$ python3 -m венв венв
$ source venv/bin/activate # создайте виртуальную среду, чтобы не загрязнять вашу систему
$ pip3 install --upgrade pip
$ pip3 установить брелок
$ dbus-run-session -- sh # это приведет вас в новую оболочку D-bus
$ echo 'somecredstorepass' | gnome-keyring-daemon --unlock # разблокировать системный брелок
$ питон
>>> импортировать брелок
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring объект по адресу 0x7f9b9c971ba8>
>>> keyring.set_password("система", "имя пользователя", "пароль")
>>> keyring.get_password("система", "имя пользователя")
'пароль'
Библиотека ключей имеет несколько функций:
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.errors.KeyringError : базовый класс ошибок для всех исключений в библиотеке ключей.keyring.errors.InitError : возникает, когда связку ключей невозможно инициализировать.keyring.errors.PasswordSetError : возникает, когда пароль не может быть установлен в связке ключей.keyring.errors.PasswordDeleteError : возникает, когда пароль не может быть удален в связке ключей. Библиотека ключей Python — это проект открытого сообщества, который с радостью приветствует участников.
Перед использованием этой библиотеки у каждого встроенного бэкэнда могут возникнуть вопросы безопасности, которые необходимо понять. Авторам инструментов или библиотек, использующих keyring , рекомендуется учитывать эти опасения.
Как и любой список известных проблем безопасности, этот список не является исчерпывающим. Дополнительные задачи могут быть добавлены по мере необходимости.
keyring из того же исполняемого файла Python, при этом операционная система не запрашивает у пользователя пароль. Чтобы какой-либо конкретный секрет запрашивал пароль при каждом доступе, найдите учетные данные с помощью приложения Keychain Access и в настройках Access Control удалите Python из списка разрешенных приложений.В этом проекте используются автоматизированные выпуски и непрерывная интеграция. Простой рабочий процесс — пометить коммит и отправить его на Github. Если он пройдет тесты в CI, он будет автоматически развернут в PyPI.
Другие вещи, которые следует учитывать при выпуске релиза:
Тесты постоянно запускаются в Github Actions.
Чтобы запустить тесты локально, установите и вызовите tox.
Проект был основан на идее Тарека Зиаде, изложенной в этом посте. Кан Чжан первоначально реализовал это как проект Google Summer of Code, и Тарек был наставником Канга в этом проекте.
Доступно как часть подписки Tidelift.
Этот проект и сопровождающие тысяч других пакетов работают с Tidelift над предоставлением одной корпоративной подписки, охватывающей все используемые вами открытые исходные коды.
Узнать больше.
