keyring
v25.5.0
La biblioteca de llaveros de Python proporciona una manera fácil de acceder al servicio de llaveros del sistema desde Python. Se puede utilizar en cualquier aplicación que necesite un almacenamiento seguro de contraseñas.
Se admiten estos backends de llavero recomendados:
Otras implementaciones de llaveros están disponibles a través de backends de terceros.
En Linux, el backend de KWallet se basa en dbus-python, que no siempre se instala correctamente cuando se usa pip (se necesita compilación). Para obtener mejores resultados, instale dbus-python como paquete del sistema.
El llavero de macOS es compatible con macOS 11 (Big Sur) y posterior requiere Python 3.8.7 o posterior con el binario "universal2". Consulte el n.° 525 para obtener más detalles.
El uso básico del llavero es bastante simple: simplemente llame keyring.set_password y keyring.get_password :
>>> importar llavero
>>> keyring.set_password("sistema", "nombre de usuario", "contraseña")
>>> keyring.get_password("sistema", "nombre de usuario")
'contraseña'
Keyring proporciona un comando keyring que se instala con el paquete. Después de instalar el conjunto de claves en la mayoría de los entornos, el comando debería estar disponible para configurar, obtener y eliminar contraseñas. Para obtener más información de uso, invoque sin argumentos o con --help así:
$ llavero --ayuda $ conjunto de llaveros nombre de usuario del sistema Contraseña para 'nombre de usuario' en 'sistema': $ llavero obtener nombre de usuario del sistema contraseña
La funcionalidad de la línea de comandos también se expone como un paquete ejecutable, adecuado para invocar desde Python de la siguiente manera:
$ python -m llavero --ayuda $ python -m conjunto de llaveros nombre de usuario del sistema Contraseña para 'nombre de usuario' en 'sistema': $ python -m llavero obtener nombre de usuario del sistema contraseña
Si se instala a través de un administrador de paquetes (apt, pacman, nix, homebrew, etc.), es posible que estas terminaciones de shell ya se hayan distribuido con el paquete (no se requiere ninguna acción).
Keyring proporciona finalización con tabulación si está instalado el complemento completion :
$ pip install 'llavero[finalización]'
Luego, genera terminaciones de shell, algo como:
$ llavero --print-completion bash | sudo tee /usr/share/bash-completion/completions/keyring $ llavero --print-completion zsh | sudo tee /usr/share/zsh/site-functions/_keyring $ llavero --print-completion tcsh | sudo tee /etc/profile.d/keyring.csh
Nota : la ruta de /usr/share es principalmente para GNU/Linux. Para otros sistemas operativos, considere:
Después de instalar las terminaciones de shell, habilítelas siguiendo las instrucciones recomendadas de su shell. p.ej:
. /usr/share/bash-completion/bash_completion en ~/.bashrc .autoload -Uz compinit && compinit aparezca en ~/.zshrc , luego grep -w keyring ~/.zcompdump para verificar que aparezca el llavero, lo que indica que se instaló correctamente. La biblioteca de llaveros de Python contiene implementaciones para varios backends. La biblioteca intentará elegir automáticamente el backend más adecuado para el entorno actual. Los usuarios también pueden especificar el conjunto de claves preferido en un archivo de configuración o llamando a la función set_keyring() .
La configuración se almacena en un archivo llamado "keyringrc.cfg" que se encuentra en una ubicación específica de la plataforma. Para determinar dónde se almacena el archivo de configuración, ejecute keyring diagnose .
Para especificar un backend de llavero, establezca la opción default-keyring en la ruta completa de la clase para ese backend, como keyring.backends.macOS.Keyring .
Si se indica keyring-path , keyring agregará esa ruta a la ruta de búsqueda del módulo Python antes de cargar el backend.
Por ejemplo, esta configuración podría usarse para cargar SimpleKeyring desde el módulo simplekeyring en el directorio ./demo (no implementado):
[parte trasera] llavero-predeterminado=llavero simple.Llavero simple ruta-llavero=demostración
Además de los backends proporcionados por el paquete principal de llaveros para los casos de uso más comunes y seguros, hay implementaciones de backends de llaveros adicionales disponibles para otros casos de uso. Simplemente instálelos para que estén disponibles:
keyring<24 ). La interfaz para el backend está definida por keyring.backend.KeyringBackend . Cada backend debe derivar de esa clase base y definir un atributo priority y tres funciones: get_password() , set_password() y delete_password() . La función get_credential() se puede definir si se desea.
Consulte el módulo backend para obtener más detalles sobre la interfaz de esta clase.
Keyring emplea puntos de entrada para permitir que cualquier paquete de terceros implemente backends sin ninguna modificación en el llavero en sí. Se anima a aquellos interesados en crear nuevos backends a crear nuevos paquetes de terceros en el espacio de nombres keyrings , de una manera modelada por el paquete keyrings.alt. Consulte el archivo setup.cfg de ese proyecto para obtener sugerencias sobre cómo crear los puntos de entrada necesarios. Se puede considerar la inclusión de backends que resulten esenciales en la biblioteca principal, aunque la facilidad de instalación de estos paquetes de terceros debería significar que las extensiones pueden estar fácilmente disponibles.
Para crear una extensión para Keyring, envíe una solicitud de extracción para que su extensión se mencione como una extensión disponible.
Keyring además permite la configuración programática del backend llamando a la API set_keyring() . El backend indicado se utilizará posteriormente para almacenar y recuperar contraseñas.
Para invocar set_keyring :
# definir una nueva clase de llavero que extiende KeyringBackend
importar llavero.backend
clase TestKeyring(keyring.backend.KeyringBackend):
"""Un llavero de prueba que siempre genera la misma contraseña
"""
prioridad = 1
def set_password(self, nombre de servicio, nombre de usuario, contraseña):
aprobar
def get_password(self, nombre de servicio, nombre de usuario):
devolver "contraseña de TestKeyring"
def eliminar_contraseña(self, nombre de servicio, nombre de usuario):
aprobar
# establecer el llavero para la biblioteca de llaveros
keyring.set_keyring(TestKeyring())
# invocar la biblioteca de llaveros
intentar:
keyring.set_password("servicio de demostración", "tarek", "pasexample")
print("contraseña almacenada exitosamente")
excepto keyring.errors.PasswordSetError:
print("no se pudo almacenar la contraseña")
print("contraseña", keyring.get_password("servicio de demostración", "tarek"))
En muchos casos, nunca será necesario desinstalar el llavero. Especialmente en Windows y macOS, el comportamiento del conjunto de claves suele ser degenerado, lo que significa que devolverá valores vacíos a la persona que llama, lo que le permitirá recurrir a algún otro comportamiento.
En algunos casos, el comportamiento predeterminado del conjunto de claves no es deseable y sería preferible desactivarlo por completo. Existen varios mecanismos para desactivar el llavero:
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring en el entorno y se utilizará el backend Null (degenerado). Este enfoque afecta a todos los usos de Keyring donde se establece esa variable.keyring --disable o python -m keyring --disable . Este enfoque afecta a todos los usos del llavero para ese usuario. Keyring proporciona un mecanismo para alterar el comportamiento del keyring a través de variables de entorno. Cada backend implementa un KeyringBackend.set_properties_from_env , que cuando se invoca encontrará todas las variables de entorno que comienzan con KEYRING_PROPERTY_{NAME} y establecerá una propiedad para cada {NAME.lower()} en el llavero. Este método se invoca durante la inicialización del conjunto de claves predeterminado/configurado.
Este mecanismo se puede utilizar para establecer algunos valores útiles en varios conjuntos de claves, incluidos:
La siguiente es una transcripción completa para instalar un llavero en un entorno virtual en Ubuntu 16.04. No se utilizó ningún archivo de configuración:
$ sudo apto instalar python3-venv libdbus-glib-1-dev
$cd/tmp
$ pyvenv py3
$ fuente py3/bin/activar
$ pip instalar -U pip
$ pip instalar almacenamiento secreto dbus-python
$ pip instalar llavero
$ pitón
>>> importar llavero
>>> llavero.get_keyring()
<keyring.backends.SecretService.Keyring objeto en 0x7f9b9c971ba8>
>>> keyring.set_password("sistema", "nombre de usuario", "contraseña")
>>> keyring.get_password("sistema", "nombre de usuario")
'contraseña'
Es posible utilizar el backend de SecretService en sistemas Linux sin un servidor X11 disponible (solo se requiere D-Bus). En este caso:
Instale el demonio de llavero de GNOME.
Inicie una sesión de D-Bus, por ejemplo, ejecute dbus-run-session -- sh y ejecute los siguientes comandos dentro de ese shell.
Ejecute gnome-keyring-daemon con la opción --unlock . La descripción de esa opción dice:
Lea una contraseña de stdin y úsela para desbloquear el conjunto de claves de inicio de sesión o créela si el conjunto de claves de inicio de sesión no existe.
Cuando se inicie ese comando, ingrese una contraseña en stdin y presione Ctrl+D (fin de datos). Después de eso, el demonio se bifurcará en segundo plano (use la opción --foreground para bloquear).
Ahora puede utilizar el backend de SecretService de Keyring. Recuerde ejecutar su aplicación en la misma sesión de D-Bus que el demonio.
También es posible utilizar un llavero con el backend de SecretService en contenedores Docker. Todo lo que necesita hacer es instalar las dependencias necesarias y agregar el indicador --privileged para evitar errores de Operación no permitida al intentar desbloquear el conjunto de claves del sistema.
La siguiente es una transcripción completa para instalar el llavero en un contenedor Ubuntu 18:04:
ventana acoplable ejecutar -it -d --ubuntu privilegiado: 18.04
$ apt-obtener actualización
$ apto instalar -y gnome-keyring python3-venv python3-dev
$ python3 -m venv venv
$ source venv/bin/activate # genera un entorno virtual para evitar contaminar su sistema
$ pip3 instalar --actualizar pip
$ pip3 instalar llavero
$ dbus-run-session -- sh # esto lo llevará a un nuevo shell D-bus
$ echo 'algún paso de tienda cred' | gnome-keyring-daemon --unlock # desbloquea el llavero del sistema
$ pitón
>>> importar llavero
>>> llavero.get_keyring()
<keyring.backends.SecretService.Keyring objeto en 0x7f9b9c971ba8>
>>> keyring.set_password("sistema", "nombre de usuario", "contraseña")
>>> keyring.get_password("sistema", "nombre de usuario")
'contraseña'
La biblioteca de llaveros tiene algunas funciones:
get_keyring() : Devuelve la implementación del conjunto de claves actualmente cargada.get_password(service, username) : devuelve la contraseña almacenada en el conjunto de claves activo. Si la contraseña no existe, devolverá Ninguna.get_credential(service, username) : devuelve un objeto de credencial almacenado en el llavero activo. Este objeto contiene al menos atributos username y password para el servicio especificado, donde el username devuelto puede ser diferente del argumento.set_password(service, username, password) : almacena la contraseña en el llavero.delete_password(service, username) : elimina la contraseña almacenada en el llavero. Si la contraseña no existe, generará una excepción. En todos los casos, los parámetros ( service , username , password ) deben ser texto Unicode.
La biblioteca de llaveros plantea las siguientes excepciones:
keyring.errors.KeyringError : clase de error base para todas las excepciones en la biblioteca de llaveros.keyring.errors.InitError : se genera cuando el conjunto de claves no se puede inicializar.keyring.errors.PasswordSetError : se produce cuando la contraseña no se puede establecer en el conjunto de claves.keyring.errors.PasswordDeleteError : se genera cuando la contraseña no se puede eliminar en el conjunto de claves. Python keyring lib es un proyecto comunitario abierto y da la bienvenida con entusiasmo a los contribuyentes.
Cada backend integrado puede tener consideraciones de seguridad que debe comprender antes de utilizar esta biblioteca. Se anima a los autores de herramientas o bibliotecas que utilizan keyring a considerar estas preocupaciones.
Como ocurre con cualquier lista de problemas de seguridad conocidos, esta lista no es exhaustiva. Se pueden agregar problemas adicionales según sea necesario.
keyring desde ese mismo ejecutable de Python sin que el sistema operativo solicite una contraseña al usuario. Para hacer que un secreto específico solicite una contraseña cada vez que se accede a él, ubique la credencial usando la aplicación Keychain Access y, en la configuración Access Control , elimine Python de la lista de aplicaciones permitidas.Este proyecto hace uso de lanzamientos automatizados e integración continua. El flujo de trabajo simple consiste en etiquetar una confirmación y enviarla a Github. Si pasa las pruebas en CI, se implementará automáticamente en PyPI.
Otras cosas a considerar al realizar un lanzamiento:
Las pruebas se ejecutan continuamente en Github Actions.
Para ejecutar las pruebas localmente, instale e invoque tox.
El proyecto se basó en la idea de Tarek Ziade en esta publicación. Kang Zhang inicialmente lo llevó a cabo como un proyecto de Google Summer of Code, y Tarek fue el mentor de Kang en este proyecto.
Disponible como parte de la suscripción Tidelift.
Este proyecto y los mantenedores de miles de otros paquetes están trabajando con Tidelift para ofrecer una suscripción empresarial que cubra todo el código abierto que utiliza.
Obtenga más información.
