keyring
v25.5.0
La bibliothèque de trousseaux de clés Python offre un moyen simple d'accéder au service de trousseaux de clés système à partir de Python. Il peut être utilisé dans n’importe quelle application nécessitant un stockage sécurisé de mots de passe.
Ces backends de trousseaux de clés recommandés sont pris en charge :
D'autres implémentations de trousseaux de clés sont disponibles via des backends tiers.
Sous Linux, le backend de KWallet s'appuie sur dbus-python, qui ne s'installe pas toujours correctement lors de l'utilisation de pip (une compilation est nécessaire). Pour de meilleurs résultats, installez dbus-python en tant que package système.
Le trousseau macOS prend en charge macOS 11 (Big Sur) et les versions ultérieures nécessitent Python 3.8.7 ou version ultérieure avec le binaire « universal2 ». Voir #525 pour plus de détails.
L'utilisation de base de keyring est assez simple : il suffit d'appeler keyring.set_password et keyring.get_password :
>>> importer un porte-clés
>>> keyring.set_password("système", "nom d'utilisateur", "mot de passe")
>>> keyring.get_password("système", "nom d'utilisateur")
'mot de passe'
Keyring fournit une commande keyring qui est installée avec le package. Après avoir installé le trousseau de clés dans la plupart des environnements, la commande devrait être disponible pour définir, obtenir et supprimer des mots de passe. Pour plus d'informations sur l'utilisation, invoquez sans argument ou avec --help comme ceci :
$ porte-clés --help $ trousseau de clés définissant le nom d'utilisateur du système Mot de passe pour « nom d'utilisateur » dans « système » : $ le trousseau obtient le nom d'utilisateur du système mot de passe
La fonctionnalité de ligne de commande est également exposée sous la forme d'un package exécutable, adapté à l'appel depuis Python comme suit :
$ python -m porte-clés --help $ python -m trousseau de clés définissant le nom d'utilisateur du système Mot de passe pour « nom d'utilisateur » dans « système » : $ python -m keyring obtient le nom d'utilisateur du système mot de passe
Si elles sont installées via un gestionnaire de packages (apt, pacman, nix, homebrew, etc.), ces complétions de shell peuvent déjà avoir été distribuées avec le package (aucune action requise).
Keyring fournit la complétion des onglets si l' completion supplémentaire est installée :
$ pip install 'porte-clés[achèvement]'
Ensuite, générez des complétions de shell, quelque chose comme :
$ porte-clés --print-completion bash | sudo tee /usr/share/bash-completion/completions/keyring $ porte-clés --print-completion zsh | sudo tee /usr/share/zsh/site-functions/_keyring $ porte-clés --print-completion tcsh | sudo tee /etc/profile.d/keyring.csh
Remarque : le chemin de /usr/share est principalement pour GNU/Linux. Pour les autres systèmes d'exploitation, pensez à :
Après avoir installé les complétions du shell, activez-les en suivant les instructions recommandées par votre shell. par exemple :
. /usr/share/bash-completion/bash_completion dans ~/.bashrc .autoload -Uz compinit && compinit apparaît dans ~/.zshrc , puis grep -w keyring ~/.zcompdump pour vérifier que le keyring apparaît, indiquant qu'il a été correctement installé. La bibliothèque de porte-clés Python contient des implémentations pour plusieurs backends. La bibliothèque tentera de choisir automatiquement le backend le plus adapté à l'environnement actuel. Les utilisateurs peuvent également spécifier le trousseau préféré dans un fichier de configuration ou en appelant la fonction set_keyring() .
La configuration est stockée dans un fichier nommé « keyringrc.cfg » trouvé dans un emplacement spécifique à la plateforme. Pour déterminer où le fichier de configuration est stocké, exécutez keyring diagnose .
Pour spécifier un backend de trousseau de clés, définissez l'option default-keyring sur le chemin complet de la classe pour ce backend, par exemple keyring.backends.macOS.Keyring .
Si keyring-path est indiqué, keyring ajoutera ce chemin au chemin de recherche du module Python avant de charger le backend.
Par exemple, cette configuration peut être utilisée pour charger le SimpleKeyring à partir du module simplekeyring dans le répertoire ./demo (non implémenté) :
[back-end] default-keyring=simplekeyring.SimpleKeyring chemin du porte-clés = démo
En plus des backends fournis par le package de trousseaux de base pour les cas d'utilisation les plus courants et les plus sécurisés, il existe des implémentations de backend de trousseaux supplémentaires disponibles pour d'autres cas d'utilisation. Installez-les simplement pour les rendre disponibles :
keyring<24 ). L'interface du backend est définie par keyring.backend.KeyringBackend . Chaque backend doit dériver de cette classe de base et définir un attribut priority et trois fonctions : get_password() , set_password() et delete_password() . La fonction get_credential() peut être définie si vous le souhaitez.
Voir le module backend pour plus de détails sur l'interface de cette classe.
Keyring utilise des points d'entrée pour permettre à tout package tiers d'implémenter des backends sans aucune modification du trousseau lui-même. Ceux qui souhaitent créer de nouveaux backends sont encouragés à créer de nouveaux packages tiers dans l'espace de noms keyrings , d'une manière modélisée par le package keyrings.alt. Consultez le fichier setup.cfg de ce projet pour obtenir des conseils sur la façon de créer les points d'entrée requis. Les backends qui s'avèrent essentiels peuvent être envisagés pour être inclus dans la bibliothèque principale, bien que la facilité d'installation de ces packages tiers devrait signifier que des extensions peuvent être facilement disponibles.
Pour créer une extension pour Keyring, veuillez soumettre une pull request pour que votre extension soit mentionnée comme extension disponible.
Keyring permet en outre la configuration programmatique du backend appelant l'api set_keyring() . Le backend indiqué sera ensuite utilisé pour stocker et récupérer les mots de passe.
Pour appeler set_keyring :
# définir une nouvelle classe de porte-clés qui étend le KeyringBackend
importer un porte-clés.backend
classe TestKeyring(keyring.backend.KeyringBackend) :
"""Un trousseau de test qui génère toujours le même mot de passe
"""
priorité = 1
def set_password (soi, nom du service, nom d'utilisateur, mot de passe) :
passer
def get_password (self, nom du service, nom d'utilisateur) :
renvoie "le mot de passe de TestKeyring"
def delete_password (soi, nom du service, nom d'utilisateur) :
passer
# définir le trousseau de clés pour la bibliothèque de trousseaux
keyring.set_keyring(TestKeyring())
# invoque la bibliothèque du trousseau de clés
essayer:
keyring.set_password("demo-service", "tarek", "passexample")
print("mot de passe stocké avec succès")
sauf keyring.errors.PasswordSetError :
print("échec de stockage du mot de passe")
print("mot de passe", keyring.get_password("demo-service", "tarek"))
Dans de nombreux cas, la désinstallation du trousseau de clés ne sera jamais nécessaire. Surtout sous Windows et macOS, le comportement du trousseau de clés est généralement dégénéré, ce qui signifie qu'il renverra des valeurs vides à l'appelant, lui permettant ainsi de revenir à un autre comportement.
Dans certains cas, le comportement par défaut du trousseau de clés n'est pas souhaitable et il serait préférable de désactiver complètement le comportement du trousseau de clés. Il existe plusieurs mécanismes pour désactiver le trousseau de clés :
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring dans l'environnement et le backend Null (dégénéré) sera utilisé. Cette approche affecte toutes les utilisations de Keyring où cette variable est définie.keyring --disable ou python -m keyring --disable . Cette approche affecte toutes les utilisations du trousseau pour cet utilisateur. Keyring fournit un mécanisme pour modifier le comportement du trousseau via des variables d'environnement. Chaque backend implémente un KeyringBackend.set_properties_from_env , qui, une fois invoqué, trouvera toutes les variables d'environnement commençant par KEYRING_PROPERTY_{NAME} et définira une propriété pour chaque {NAME.lower()} sur le trousseau de clés. Cette méthode est invoquée lors de l'initialisation du trousseau de clés par défaut/configuré.
Ce mécanisme peut être utilisé pour définir certaines valeurs utiles sur divers trousseaux de clés, notamment :
Ce qui suit est une transcription complète pour l'installation d'un trousseau de clés dans un environnement virtuel sur Ubuntu 16.04. Aucun fichier de configuration n'a été utilisé :
$ sudo apt installer python3-venv libdbus-glib-1-dev
$ cd/tmp
$ pyvenv py3
$ source py3/bin/activer
$ pip installer -U pip
$ pip installer secretstorage dbus-python
$ pip installer le porte-clés
$python
>>> importer un porte-clés
>>> porte-clés.get_keyring()
<objet keyring.backends.SecretService.Keyring à 0x7f9b9c971ba8>
>>> keyring.set_password("système", "nom d'utilisateur", "mot de passe")
>>> keyring.get_password("système", "nom d'utilisateur")
'mot de passe'
Il est possible d'utiliser le backend SecretService sur les systèmes Linux sans serveur X11 disponible (seul D-Bus est requis). Dans ce cas:
Installez le démon GNOME Keyring.
Démarrez une session D-Bus, par exemple exécutez dbus-run-session -- sh et exécutez les commandes suivantes dans ce shell.
Exécutez gnome-keyring-daemon avec l'option --unlock . La description de cette option dit :
Lisez un mot de passe depuis stdin et utilisez-le pour déverrouiller le trousseau de connexion ou créez-le si le trousseau de connexion n'existe pas.
Lorsque cette commande est lancée, entrez un mot de passe dans stdin et appuyez sur Ctrl+D (fin des données). Après cela, le démon passera en arrière-plan (utilisez l'option --foreground pour bloquer).
Vous pouvez désormais utiliser le backend SecretService de Keyring. N'oubliez pas d'exécuter votre application dans la même session D-Bus que le démon.
Il est également possible d'utiliser un trousseau de clés avec le backend SecretService dans les conteneurs Docker. Tout ce que vous avez à faire est d'installer les dépendances nécessaires et d'ajouter l'indicateur --privileged pour éviter toute erreur d'opération non autorisée lors de la tentative de déverrouillage du trousseau du système.
Ce qui suit est une transcription complète pour l'installation d'un trousseau de clés sur un conteneur Ubuntu 18:04 :
docker run -it -d --privileged ubuntu:18.04
$ apt-get mise à jour
$ apt install -y gnome-keyring python3-venv python3-dev
$ python3 -m venv venv
$ source venv/bin/activate # source un environnement virtuel pour éviter de polluer votre système
$ pip3 install --upgrade pip
$ pip3 installer le porte-clés
$ dbus-run-session -- sh # cela vous déposera dans un nouveau shell D-bus
$ echo 'somecredstorepass' | gnome-keyring-daemon --unlock # déverrouiller le trousseau du système
$python
>>> importer un porte-clés
>>> porte-clés.get_keyring()
<objet keyring.backends.SecretService.Keyring à 0x7f9b9c971ba8>
>>> keyring.set_password("système", "nom d'utilisateur", "mot de passe")
>>> keyring.get_password("système", "nom d'utilisateur")
'mot de passe'
La lib keyring a quelques fonctions :
get_keyring() : renvoie l'implémentation du trousseau de clés actuellement chargé.get_password(service, username) : Renvoie le mot de passe stocké dans le trousseau actif. Si le mot de passe n'existe pas, il renverra Aucun.get_credential(service, username) : renvoie un objet d'identification stocké dans le trousseau actif. Cet objet contient au moins les attributs username et password pour le service spécifié, le username renvoyé pouvant être différent de l'argument.set_password(service, username, password) : Stocke le mot de passe dans le trousseau.delete_password(service, username) : Supprimez le mot de passe stocké dans le trousseau. Si le mot de passe n'existe pas, une exception sera déclenchée. Dans tous les cas, les paramètres ( service , username , password ) doivent être du texte Unicode.
La bibliothèque de trousseaux de clés génère les exceptions suivantes :
keyring.errors.KeyringError : classe d'erreur de base pour toutes les exceptions dans la bibliothèque de porte-clés.keyring.errors.InitError : déclenché lorsque le trousseau de clés ne peut pas être initialisé.keyring.errors.PasswordSetError : déclenché lorsque le mot de passe ne peut pas être défini dans le trousseau de clés.keyring.errors.PasswordDeleteError : déclenché lorsque le mot de passe ne peut pas être supprimé dans le trousseau de clés. Python keyring lib est un projet communautaire ouvert et accueille avec impatience les contributeurs.
Chaque backend intégré peut avoir des considérations de sécurité à comprendre avant d'utiliser cette bibliothèque. Les auteurs d'outils ou de bibliothèques utilisant keyring sont encouragés à prendre en compte ces préoccupations.
Comme pour toute liste de problèmes de sécurité connus, cette liste n’est pas exhaustive. Des problèmes supplémentaires peuvent être ajoutés si nécessaire.
keyring à partir de ce même exécutable Python sans que le système d'exploitation ne demande à l'utilisateur un mot de passe. Pour qu'un secret spécifique demande un mot de passe à chaque accès, localisez les informations d'identification à l'aide de l'application Keychain Access et, dans les paramètres Access Control , supprimez Python de la liste des applications autorisées.Ce projet utilise des versions automatisées et une intégration continue. Le flux de travail simple consiste à marquer un commit et à le transmettre à Github. S'il réussit les tests dans CI, il sera automatiquement déployé sur PyPI.
Autres éléments à prendre en compte lors de la création d'une version :
Les tests sont exécutés en continu dans Github Actions.
Pour exécuter les tests localement, installez et appelez tox.
Le projet était basé sur l'idée de Tarek Ziade dans ce post. Kang Zhang l'a initialement réalisé dans le cadre d'un projet Google Summer of Code, et Tarek a encadré Kang sur ce projet.
Disponible dans le cadre de l’abonnement Tidelift.
Ce projet et les responsables de milliers d'autres packages travaillent avec Tidelift pour proposer un abonnement d'entreprise qui couvre tout l'open source que vous utilisez.
Apprendre encore plus.
