keyring
v25.5.0
Pustaka keyring Python menyediakan cara mudah untuk mengakses layanan keyring sistem dari python. Ini dapat digunakan di aplikasi apa pun yang memerlukan penyimpanan kata sandi yang aman.
Backend keyring yang direkomendasikan ini didukung:
Implementasi keyring lainnya tersedia melalui Backend Pihak Ketiga.
Di Linux, backend KWallet bergantung pada dbus-python, yang tidak selalu diinstal dengan benar saat menggunakan pip (diperlukan kompilasi). Untuk hasil terbaik, instal dbus-python sebagai paket sistem.
gantungan kunci macOS mendukung macOS 11 (Big Sur) dan lebih baru memerlukan Python 3.8.7 atau lebih baru dengan biner "universal2". Lihat #525 untuk detailnya.
Penggunaan dasar keyring cukup sederhana: cukup panggil keyring.set_password dan keyring.get_password :
>>> impor gantungan kunci
>>> keyring.set_password("sistem", "nama pengguna", "kata sandi")
>>> keyring.get_password("sistem", "nama pengguna")
'kata sandi'
Keyring menyediakan perintah keyring yang diinstal bersama paket. Setelah menginstal keyring di sebagian besar lingkungan, perintah harus tersedia untuk mengatur, mendapatkan, dan menghapus kata sandi. Untuk informasi penggunaan lebih lanjut, aktifkan tanpa argumen atau dengan --help seperti:
$ gantungan kunci --membantu $ keyring mengatur nama pengguna sistem Kata sandi untuk 'nama pengguna' di 'sistem': $ gantungan kunci dapatkan nama pengguna sistem kata sandi
Fungsionalitas baris perintah juga diekspos sebagai paket yang dapat dieksekusi, cocok untuk dipanggil dari Python seperti:
$ python -m gantungan kunci --membantu $ python -m gantungan kunci setel nama pengguna sistem Kata sandi untuk 'nama pengguna' di 'sistem': $ python -m keyring dapatkan nama pengguna sistem kata sandi
Jika diinstal melalui manajer paket (apt, pacman, nix, homebrew, dll), penyelesaian shell ini mungkin sudah didistribusikan bersama paket (tidak diperlukan tindakan apa pun).
Keyring menyediakan penyelesaian tab jika tambahan completion diinstal:
$ pip install 'gantungan kunci[penyelesaian]'
Kemudian, buat penyelesaian shell, seperti:
$ gantungan kunci --print-completion bash | sudo tee /usr/share/bash-completion/completions/keyring $ gantungan kunci --penyelesaian cetak zsh | sudo tee /usr/share/zsh/site-functions/_keyring $ gantungan kunci --penyelesaian cetak tcsh | sudo tee /etc/profile.d/keyring.csh
Catatan : jalur /usr/share terutama untuk GNU/Linux. Untuk OS lain, pertimbangkan:
Setelah menginstal penyelesaian shell, aktifkan dengan mengikuti instruksi yang direkomendasikan shell Anda. misalnya:
. /usr/share/bash-completion/bash_completion di ~/.bashrc .autoload -Uz compinit && compinit muncul di ~/.zshrc , lalu grep -w keyring ~/.zcompdump untuk memverifikasi keyring muncul, menunjukkan bahwa itu telah diinstal dengan benar. Lib keyring python berisi implementasi untuk beberapa backend. Perpustakaan akan mencoba memilih backend yang paling sesuai secara otomatis untuk lingkungan saat ini. Pengguna juga dapat menentukan keyring pilihan dalam file konfigurasi atau dengan memanggil fungsi set_keyring() .
Konfigurasi disimpan dalam file bernama "keyringrc.cfg" yang ditemukan di lokasi spesifik platform. Untuk menentukan di mana file konfigurasi disimpan, jalankan keyring diagnose .
Untuk menentukan backend keyring, atur opsi default-keyring ke jalur lengkap kelas untuk backend tersebut, seperti keyring.backends.macOS.Keyring .
Jika jalur gantungan kunci ditunjukkan, gantungan kunci akan menambahkan jalur tersebut ke jalur pencarian modul Python sebelum memuat backend.
Misalnya, konfigurasi ini mungkin digunakan untuk memuat SimpleKeyring dari modul simplekeyring di direktori ./demo (tidak diterapkan):
[bagian belakang] default-keyring=simplekeyring.SimpleKeyring jalur gantungan kunci=demo
Selain backend yang disediakan oleh paket keyring inti untuk kasus penggunaan paling umum dan aman, terdapat implementasi backend keyring tambahan yang tersedia untuk kasus penggunaan lainnya. Cukup instal untuk membuatnya tersedia:
keyring<24 ). Antarmuka untuk backend ditentukan oleh keyring.backend.KeyringBackend . Setiap backend harus berasal dari kelas dasar tersebut dan menentukan atribut priority dan tiga fungsi: get_password() , set_password() , dan delete_password() . Fungsi get_credential() dapat ditentukan jika diinginkan.
Lihat modul backend untuk detail lebih lanjut tentang antarmuka kelas ini.
Keyring menggunakan titik masuk untuk memungkinkan paket pihak ketiga mengimplementasikan backend tanpa modifikasi apa pun pada keyring itu sendiri. Mereka yang tertarik untuk membuat backend baru didorong untuk membuat paket pihak ketiga baru di namespace keyrings , dengan cara yang dimodelkan oleh paket keyrings.alt. Lihat file setup.cfg di proyek tersebut untuk mendapatkan petunjuk tentang cara membuat titik masuk yang diperlukan. Backend yang terbukti penting dapat dipertimbangkan untuk disertakan dalam perpustakaan inti, meskipun kemudahan menginstal paket pihak ketiga ini berarti bahwa ekstensi mungkin sudah tersedia.
Untuk membuat ekstensi untuk Keyring, kirimkan permintaan tarik agar ekstensi Anda disebutkan sebagai ekstensi yang tersedia.
Keyring juga memungkinkan konfigurasi terprogram dari backend yang memanggil api set_keyring() . Backend yang ditunjukkan selanjutnya akan digunakan untuk menyimpan dan mengambil kata sandi.
Untuk memanggil set_keyring :
# tentukan kelas keyring baru yang memperluas KeyringBackend
impor gantungan kunci.backend
kelas TestKeyring(keyring.backend.KeyringBackend):
"""Gantungan kunci uji yang selalu menghasilkan kata sandi yang sama
"""
prioritas = 1
def set_password(diri, nama layanan, nama pengguna, kata sandi):
lulus
def get_password(diri, nama layanan, nama pengguna):
kembalikan "kata sandi dari TestKeyring"
def delete_password(diri, nama layanan, nama pengguna):
lulus
# atur gantungan kunci untuk lib gantungan kunci
gantungan kunci.set_keyring(TestKeyring())
# aktifkan lib keyring
mencoba:
keyring.set_password("layanan demo", "tarek", "passexample")
print("password berhasil disimpan")
kecuali keyring.errors.PasswordSetError:
print("Gagal menyimpan password")
print("kata sandi", keyring.get_password("layanan demo", "tarek"))
Dalam banyak kasus, menghapus instalasi keyring tidak diperlukan lagi. Khususnya pada Windows dan macOS, perilaku keyring biasanya menurun, yang berarti ia akan mengembalikan nilai kosong ke pemanggil, sehingga pemanggil dapat kembali ke perilaku lain.
Dalam beberapa kasus, perilaku default keyring tidak diinginkan dan akan lebih baik jika perilaku keyring dinonaktifkan sama sekali. Ada beberapa mekanisme untuk menonaktifkan keyring:
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring di lingkungan, dan backend Null (degenerate) akan digunakan. Pendekatan ini mempengaruhi semua penggunaan Keyring di mana variabel tersebut diatur.keyring --disable atau python -m keyring --disable . Pendekatan ini mempengaruhi semua penggunaan keyring untuk pengguna tersebut. Keyring menyediakan mekanisme untuk mengubah perilaku keyring melalui variabel lingkungan. Setiap backend mengimplementasikan KeyringBackend.set_properties_from_env , yang bila dipanggil akan menemukan semua variabel lingkungan yang dimulai dengan KEYRING_PROPERTY_{NAME} dan akan menyetel properti untuk setiap {NAME.lower()} pada keyring. Metode ini dipanggil selama inisialisasi untuk keyring default/dikonfigurasi.
Mekanisme ini dapat digunakan untuk menetapkan beberapa nilai berguna pada berbagai gantungan kunci, termasuk:
Berikut transkrip lengkap instalasi keyring pada virtual environment di Ubuntu 16.04. Tidak ada file konfigurasi yang digunakan:
$ sudo tepat instal python3-venv libdbus-glib-1-dev
$ cd /tmp
$pyvenvpy3
$ sumber py3/bin/aktifkan
$ pip instal -U pip
$ pip instal penyimpanan rahasia dbus-python
$ pip instal gantungan kunci
$piton
>>> impor gantungan kunci
>>> gantungan kunci.get_keyring()
<objek keyring.backends.SecretService.Keyring di 0x7f9b9c971ba8>
>>> keyring.set_password("sistem", "nama pengguna", "kata sandi")
>>> keyring.get_password("sistem", "nama pengguna")
'kata sandi'
Dimungkinkan untuk menggunakan backend SecretService pada sistem Linux tanpa tersedia server X11 (hanya diperlukan D-Bus). Dalam hal ini:
Instal daemon Gantungan Kunci GNOME.
Mulai sesi D-Bus, misalnya jalankan dbus-run-session -- sh dan jalankan perintah berikut di dalam shell itu.
Jalankan gnome-keyring-daemon dengan opsi --unlock . Deskripsi opsi itu mengatakan:
Baca kata sandi dari stdin, dan gunakan untuk membuka kunci keyring login atau buat kata sandi jika keyring login tidak ada.
Saat perintah itu dimulai, masukkan kata sandi ke stdin dan tekan Ctrl+D (akhir data). Setelah itu, daemon akan bercabang ke latar belakang (gunakan opsi --foreground untuk memblokir).
Sekarang Anda dapat menggunakan backend SecretService dari Keyring. Ingatlah untuk menjalankan aplikasi Anda di sesi D-Bus yang sama dengan daemon.
Dimungkinkan juga untuk menggunakan keyring dengan backend SecretService di kontainer Docker. Yang perlu Anda lakukan hanyalah menginstal dependensi yang diperlukan dan menambahkan tanda --privileged untuk menghindari kesalahan Operasi yang tidak diizinkan saat mencoba membuka kunci keyring sistem.
Berikut transkrip lengkap instalasi keyring pada container Ubuntu 18:04:
buruh pelabuhan menjalankan -it -d --istimewa ubuntu:18.04
$ pembaruan apt-get
$ tepat instal -y gnome-keyring python3-venv python3-dev
$ python3 -m venv venv
$ source venv/bin/activate # source lingkungan virtual untuk menghindari polusi pada sistem Anda
$ pip3 instal --tingkatkan pip
$ pip3 pasang gantungan kunci
$ dbus-run-session -- sh # ini akan menjatuhkan Anda ke shell D-bus baru
$ echo 'somecredstorepass' | gnome-keyring-daemon --unlock # membuka kunci keyring sistem
$piton
>>> impor gantungan kunci
>>> gantungan kunci.get_keyring()
<objek keyring.backends.SecretService.Keyring di 0x7f9b9c971ba8>
>>> keyring.set_password("sistem", "nama pengguna", "kata sandi")
>>> keyring.get_password("sistem", "nama pengguna")
'kata sandi'
Lib keyring memiliki beberapa fungsi:
get_keyring() : Mengembalikan implementasi keyring yang sedang dimuat.get_password(service, username) : Mengembalikan kata sandi yang disimpan dalam keyring aktif. Jika kata sandi tidak ada, maka tidak ada yang akan dikembalikan.get_credential(service, username) : Mengembalikan objek kredensial yang disimpan dalam keyring aktif. Objek ini berisi setidaknya atribut username dan password untuk layanan yang ditentukan, dengan username yang dikembalikan mungkin berbeda dari argumen.set_password(service, username, password) : Simpan kata sandi di gantungan kunci.delete_password(service, username) : Hapus kata sandi yang disimpan di gantungan kunci. Jika kata sandi tidak ada, maka akan memunculkan pengecualian. Dalam semua kasus, parameter ( service , username , password ) harus berupa teks Unicode.
Lib keyring memunculkan pengecualian berikut:
keyring.errors.KeyringError : Kelas Kesalahan Dasar untuk semua pengecualian di lib keyring.keyring.errors.InitError : Dimunculkan ketika keyring tidak dapat diinisialisasi.keyring.errors.PasswordSetError : Dimunculkan ketika kata sandi tidak dapat diatur di keyring.keyring.errors.PasswordDeleteError : Dimunculkan ketika kata sandi tidak dapat dihapus di keyring. Lib keyring Python adalah proyek komunitas terbuka dan dengan penuh semangat menyambut kontributor.
Setiap backend bawaan mungkin memiliki pertimbangan keamanan yang perlu dipahami sebelum menggunakan perpustakaan ini. Penulis alat atau perpustakaan yang menggunakan keyring didorong untuk mempertimbangkan masalah ini.
Seperti daftar masalah keamanan lainnya, daftar ini tidak lengkap. Masalah tambahan dapat ditambahkan sesuai kebutuhan.
keyring dari Python yang sama yang dapat dieksekusi tanpa sistem operasi meminta kata sandi kepada pengguna. Untuk menyebabkan rahasia tertentu meminta kata sandi setiap kali diakses, temukan kredensial menggunakan aplikasi Keychain Access , dan di pengaturan Access Control , hapus Python dari daftar aplikasi yang diizinkan.Proyek ini memanfaatkan rilis otomatis dan integrasi berkelanjutan. Alur kerja sederhananya adalah memberi tag pada komit dan mendorongnya ke Github. Jika lolos pengujian di CI, maka secara otomatis akan diterapkan ke PyPI.
Hal lain yang perlu diperhatikan saat membuat rilis:
Pengujian terus dijalankan di Github Actions.
Untuk menjalankan pengujian secara lokal, instal dan aktifkan tox.
Proyek ini didasarkan pada ide Tarek Ziade di postingan ini. Kang Zhang awalnya melaksanakannya sebagai proyek Google Summer of Code, dan Tarek membimbing Kang dalam proyek ini.
Tersedia sebagai bagian dari Langganan Tidelift.
Proyek ini dan pengelola ribuan paket lainnya bekerja sama dengan Tidelift untuk menghadirkan satu langganan perusahaan yang mencakup semua sumber terbuka yang Anda gunakan.
Pelajari lebih lanjut.
