keyring
v25.5.0
Python キーリング ライブラリは、Python からシステム キーリング サービスに簡単にアクセスする方法を提供します。安全なパスワードの保管を必要とするあらゆるアプリケーションで使用できます。
次の推奨キーリング バックエンドがサポートされています。
他のキーリングの実装は、サードパーティのバックエンドを通じて利用できます。
Linux では、KWallet バックエンドは dbus-python に依存しているため、pip の使用時に正しくインストールされないことがあります (コンパイルが必要です)。最良の結果を得るには、dbus-python をシステム パッケージとしてインストールします。
macOS キーチェーンは macOS 11 (Big Sur) をサポートしており、それ以降では「universal2」バイナリを備えた Python 3.8.7 以降が必要です。詳細については #525 を参照してください。
キーリングの基本的な使用法は非常に簡単です。 keyring.set_passwordとkeyring.get_passwordを呼び出すだけです。
>>> キーリングをインポート
>>> keyring.set_password("システム", "ユーザー名", "パスワード")
>>> keyring.get_password("システム", "ユーザー名")
'パスワード'
Keyring は、パッケージとともにインストールされるkeyringコマンドを提供します。ほとんどの環境にキーリングをインストールすると、このコマンドを使用してパスワードを設定、取得、削除できるようになります。使用法の詳細については、引数を指定せずに呼び出すか、 --helpを指定して呼び出してください。
$ キーリング --ヘルプ $ keyring はシステムのユーザー名を設定します 「システム」の「ユーザー名」のパスワード: $ keyring システムのユーザー名を取得 パスワード
コマンドライン機能は実行可能パッケージとしても公開されており、次のように Python から呼び出すのに適しています。
$ python -m キーリング --help $ python -m キーリングはシステムのユーザー名を設定します 「システム」の「ユーザー名」のパスワード: $ 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 tee /etc/profile.d/keyring.csh
注: /usr/share のパスは主に GNU/Linux 用です。他の OS の場合は、以下を考慮してください。
シェル補完をインストールした後、シェルの推奨手順に従ってシェル補完を有効にします。例えば：
. /usr/share/bash-completion/bash_completion ~/.bashrc内の. /usr/share/bash-completion/bash_completion 。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 モジュール検索パスに追加します。
たとえば、この構成は、 ./demo demo ディレクトリ (未実装) のsimplekeyringモジュールからSimpleKeyringロードするために使用できます。
[バックエンド] デフォルトキーリング=simplekeyring.SimpleKeyring キーリングパス=デモ
最も一般的で安全な使用例向けにコア キーリング パッケージによって提供されるバックエンドに加えて、他の使用例で使用できる追加のキーリング バックエンド実装があります。インストールするだけで使用できるようになります。
keyring<24が必要)。 バックエンドのインターフェースはkeyring.backend.KeyringBackendによって定義されます。すべてのバックエンドはその基本クラスから派生し、 priority属性と 3 つの関数get_password() 、 set_password() 、およびdelete_password()を定義する必要があります。必要に応じてget_credential()関数を定義できます。
このクラスのインターフェイスの詳細については、 backendモジュールを参照してください。
キーリングはエントリ ポイントを採用しており、キーリング自体を変更することなく、サードパーティのパッケージがバックエンドを実装できるようにします。新しいバックエンドの作成に興味がある場合は、keyrings.alt パッケージでモデル化された方法で、 keyrings名前空間に新しいサードパーティ パッケージを作成することをお勧めします。必要なエントリ ポイントを作成する方法のヒントについては、そのプロジェクトのsetup.cfgファイルを参照してください。必須であることが判明したバックエンドは、コア ライブラリに含めることが検討される可能性がありますが、これらのサードパーティ パッケージのインストールが簡単であるということは、拡張機能がすぐに利用できることを意味します。
Keyring の拡張機能を作成するには、プル リクエストを送信して、使用可能な拡張機能として拡張機能を指定してください。
さらに、キーリングを使用すると、API set_keyring()呼び出してバックエンドをプログラムで構成できます。指定されたバックエンドは、その後、パスワードの保存と取得に使用されます。
set_keyring呼び出すには:
# KeyringBackend を拡張する新しいキーリング クラスを定義します
キーリングのインポート.バックエンド
クラス TestKeyring(keyring.backend.KeyringBackend):
"""常に同じパスワードを出力するテスト キーリング
「」
優先度 = 1
def set_password(自分自身、サービス名、ユーザー名、パスワード):
合格
def get_password(自分自身、サービス名、ユーザー名):
「TestKeyring からのパスワード」を返します
def delete_password(自分自身、サービス名、ユーザー名):
合格
# キーリング lib のキーリングを設定します
keyring.set_keyring(TestKeyring())
# キーリングライブラリを呼び出します
試す：
keyring.set_password("デモサービス", "タレク", "パス例")
print("パスワードは正常に保存されました")
keyring.errors.PasswordSetError を除く:
print("パスワードの保存に失敗しました")
print("パスワード", keyring.get_password("デモサービス", "tarek"))
多くの場合、キーリングをアンインストールする必要はありません。特に Windows と macOS では、キーリングの動作は通常縮退しています。つまり、呼び出し元に空の値が返され、呼び出し元が他の動作にフォールバックできるようになります。
場合によっては、キーリングのデフォルトの動作が望ましくないため、キーリングの動作を完全に無効にすることが望ましい場合があります。キーリングを無効にするメカニズムはいくつかあります。
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyringを設定すると、 Null (縮退) バックエンドが使用されます。このアプローチは、その変数が設定されているキーリングのすべての使用に影響します。keyring --disableまたはpython -m keyring --disableを実行して、ユーザーの Null キーリングを永続的に構成します。このアプローチは、そのユーザーのキーリングのすべての使用に影響します。 キーリングは、環境変数を通じてキーリングの動作を変更するメカニズムを提供します。各バックエンドはKeyringBackend.set_properties_from_envを実装します。これが呼び出されると、 KEYRING_PROPERTY_{NAME}で始まるすべての環境変数が検索され、キーリングの各{NAME.lower()}のプロパティが設定されます。このメソッドは、デフォルト/設定済みのキーリングの初期化中に呼び出されます。
このメカニズムは、次のようなさまざまなキーリングにいくつかの有用な値を設定するために使用できます。
以下は、Ubuntu 16.04 上の仮想環境にキーリングをインストールするための完全な転写です。構成ファイルは使用されませんでした:
$ sudo apt install python3-venv libdbus-glib-1-dev
$ cd /tmp
$ pyvenv py3
$ ソース py3/bin/activate
$ pip install -U pip
$ pip install secretstorage dbus-python
$ pip インストールキーリング
$ パイソン
>>> キーリングをインポート
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring オブジェクト (0x7f9b9c971ba8)>
>>> keyring.set_password("システム", "ユーザー名", "パスワード")
>>> keyring.get_password("システム", "ユーザー名")
'パスワード'
X11 サーバーが利用できない Linux システム上で SecretService バックエンドを使用することも可能です (D-Bus のみが必要です)。この場合：
GNOME キーリング デーモンをインストールします。
D-Bus セッションを開始します (たとえばdbus-run-session -- shを実行し、そのシェル内で次のコマンドを実行します)。
--unlockオプションを指定してgnome-keyring-daemonを実行します。そのオプションの説明には次のように書かれています。
標準入力からパスワードを読み取り、それを使用してログイン キーリングのロックを解除するか、ログイン キーリングが存在しない場合は作成します。
このコマンドが開始されたら、標準入力にパスワードを入力し、Ctrl+D (データの終わり) を押します。その後、デーモンはバックグラウンドにフォークします (ブロックするには--foregroundオプションを使用します)。
これで、Keyring の SecretService バックエンドを使用できるようになりました。アプリケーションをデーモンと同じ D-Bus セッションで実行することを忘れないでください。
Docker コンテナーの SecretService バックエンドでキーリングを使用することもできます。必要な作業は、必要な依存関係をインストールし、--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 venv venv
$ 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 lib はオープン コミュニティ プロジェクトであり、貢献者を熱心に歓迎しています。
各組み込みバックエンドには、このライブラリを使用する前に理解しておくべきセキュリティ上の考慮事項がある場合があります。 keyring利用するツールやライブラリの作成者は、これらの懸念事項を考慮することをお勧めします。
既知のセキュリティ上の懸念事項のリストと同様、このリストもすべてを網羅しているわけではありません。必要に応じて問題を追加できます。
keyringによって作成されたシークレットにアクセスできます。特定のシークレットにアクセスするたびにパスワードの入力を求めるようにするには、 Keychain Accessアプリケーションを使用して資格情報を見つけ、 Access Control設定で、許可されたアプリケーションのリストからPython削除します。このプロジェクトでは、自動リリースと継続的インテグレーションを利用しています。シンプルなワークフローは、コミットにタグを付けて Github にプッシュすることです。 CI でのテストに合格すると、自動的に PyPI にデプロイされます。
リリースを作成する際に考慮すべきその他の事項:
テストは Github Actions で継続的に実行されます。
テストをローカルで実行するには、tox をインストールして呼び出します。
このプロジェクトは、この投稿の Tarek Ziade のアイデアに基づいています。 Kang Zhang は当初、Google Summer of Code プロジェクトとしてこれを実行し、Tarek はこのプロジェクトに関して Kang を指導しました。
Tidelift サブスクリプションの一部として利用できます。
このプロジェクトと他の何千ものパッケージのメンテナーは、Tidelift と協力して、使用するすべてのオープンソースをカバーする 1 つのエンタープライズ サブスクリプションを提供しています。
もっと詳しく知る。
