keyring
v25.5.0
توفر مكتبة Python keyring طريقة سهلة للوصول إلى خدمة keyring للنظام من python. يمكن استخدامه في أي تطبيق يحتاج إلى تخزين كلمة مرور آمنة.
يتم دعم الواجهات الخلفية لحلقة المفاتيح الموصى بها:
تتوفر تطبيقات أخرى لحلقة المفاتيح من خلال الواجهات الخلفية لجهات خارجية.
في Linux، تعتمد الواجهة الخلفية لـ KWallet على dbus-python، والذي لا يتم تثبيته دائمًا بشكل صحيح عند استخدام النقطة (يلزم وجود تجميع). للحصول على أفضل النتائج، قم بتثبيت dbus-python كحزمة نظام.
تدعم سلسلة مفاتيح macOS نظام التشغيل macOS 11 (Big Sur) وتتطلب إصدارًا أحدث من Python 3.8.7 أو إصدارًا أحدث مع الثنائي "universal2". انظر رقم 525 لمزيد من التفاصيل.
الاستخدام الأساسي لحلقة المفاتيح بسيط جدًا: ما عليك سوى الاتصال keyring.set_password و keyring.get_password :
>>> حلقة مفاتيح مستوردة
>>> keyring.set_password("النظام"، "اسم المستخدم"، "كلمة المرور")
>>> keyring.get_password("النظام"، "اسم المستخدم")
'كلمة المرور'
توفر Keyring أمر keyring المثبت مع الحزمة. بعد تثبيت حلقة المفاتيح في معظم البيئات، يجب أن يكون الأمر متاحًا لإعداد كلمات المرور والحصول عليها وحذفها. لمزيد من معلومات الاستخدام، قم بالاستدعاء بدون وسيطات أو باستخدام --help كما يلي:
حلقة مفاتيح $-مساعدة $ كيرينغ تعيين اسم مستخدم النظام كلمة المرور لـ "اسم المستخدم" في "النظام": حلقة مفاتيح $ تحصل على اسم مستخدم النظام كلمة المرور
يتم أيضًا عرض وظيفة سطر الأوامر كحزمة قابلة للتنفيذ، ومناسبة للاستدعاء من Python كما يلي:
حلقة مفاتيح $ python -m --مساعدة $ python -m keyring تعيين اسم مستخدم النظام كلمة المرور لـ "اسم المستخدم" في "النظام": $ python -m keyring احصل على اسم مستخدم النظام كلمة المرور
إذا تم التثبيت عبر مدير الحزم (apt، أو pacman، أو nix، أو homebrew، وما إلى ذلك)، فمن المحتمل أن تكون إكمالات الصدفة هذه قد تم توزيعها بالفعل مع الحزمة (لا يلزم اتخاذ أي إجراء).
توفر Keyring إكمال علامة التبويب إذا تم تثبيت completion الإضافي:
$ تثبيت النقطة "حلقة مفاتيح [اكتمال]"
ثم قم بإنشاء عمليات إكمال الصدفة، مثل:
حلقة مفاتيح $ - باش لاستكمال الطباعة | Sudo Tee /usr/share/bash-completion/completions/keyring حلقة مفاتيح $ --إكمال الطباعة zsh | Sudo Tee /usr/share/zsh/site-functions/_keyring حلقة مفاتيح $ - إكمال الطباعة tcsh | سودو تي /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 للتحقق من ظهور keyring، مما يشير إلى أنه تم تثبيته بشكل صحيح. يحتوي python keyring lib على تطبيقات للعديد من الواجهات الخلفية. ستحاول المكتبة اختيار الواجهة الخلفية الأكثر ملاءمة للبيئة الحالية تلقائيًا. يمكن للمستخدمين أيضًا تحديد حلقة المفاتيح المفضلة في ملف التكوين أو عن طريق استدعاء وظيفة set_keyring() .
يتم تخزين التكوين في ملف يسمى "keyringrc.cfg" موجود في موقع خاص بالنظام الأساسي. لتحديد مكان تخزين ملف التكوين، قم بتشغيل keyring diagnose .
لتحديد واجهة خلفية لحلقة مفاتيح، قم بتعيين خيار حلقة المفاتيح الافتراضية على المسار الكامل للفئة لتلك الواجهة الخلفية، مثل keyring.backends.macOS.Keyring .
إذا تمت الإشارة إلى مسار حلقة المفاتيح ، فستضيف حلقة المفاتيح هذا المسار إلى مسار بحث وحدة Python قبل تحميل الواجهة الخلفية.
على سبيل المثال، يمكن استخدام هذا التكوين لتحميل SimpleKeyring من الوحدة simplekeyring في الدليل ./demo (لم يتم تنفيذه):
[الخلفية] default-keyring=simplekeyring.SimpleKeyring keyring-path=demo
بالإضافة إلى الواجهات الخلفية التي توفرها حزمة keyring الأساسية لحالات الاستخدام الأكثر شيوعًا وأمانًا، هناك تطبيقات خلفية إضافية متاحة لحالات الاستخدام الأخرى. ما عليك سوى تثبيتها لإتاحتها:
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
تعريف set_password (النفس، اسم الخدمة، اسم المستخدم، كلمة المرور):
يمر
تعريف get_password(self، اسم الخدمة، اسم المستخدم):
إرجاع "كلمة المرور من TestKeyring"
مواطن حذف_كلمة المرور (النفس، اسم الخدمة، اسم المستخدم):
يمر
# قم بتعيين حلقة المفاتيح لـ keyring lib
keyring.set_keyring(TestKeyring())
# استدعاء حلقة المفاتيح lib
يحاول:
keyring.set_password("الخدمة التجريبية"، "طارق"، "مثال المرور")
طباعة ("تم تخزين كلمة المرور بنجاح")
باستثناء keyring.errors.PasswordSetError:
طباعة ("فشل في تخزين كلمة المرور")
طباعة ("كلمة المرور"، 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
$ مؤتمر نزع السلاح / تمب
$ pyvenv py3
$ المصدر py3/bin/activate
$ نقطة تثبيت -U نقطة
$ نقطة تثبيت Secretstorage dbus-python
$ نقطة تثبيت كيرينغ
$ بيثون
>>> حلقة مفاتيح مستوردة
>>> 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 . يقول وصف هذا الخيار:
اقرأ كلمة المرور من stdin، واستخدمها لفتح حلقة مفاتيح تسجيل الدخول أو قم بإنشائها في حالة عدم وجود حلقة مفاتيح تسجيل الدخول.
عند بدء تشغيل هذا الأمر، أدخل كلمة المرور في stdin واضغط على Ctrl+D (نهاية البيانات). بعد ذلك، سيتفرع البرنامج الخفي إلى الخلفية (استخدم خيار --foreground للحظر).
يمكنك الآن استخدام الواجهة الخلفية SecretService لـ Keyring. تذكر تشغيل التطبيق الخاص بك في نفس جلسة D-Bus مثل البرنامج الخفي.
من الممكن استخدام حلقة المفاتيح مع الواجهة الخلفية SecretService في حاويات Docker أيضًا. كل ما عليك فعله هو تثبيت التبعيات الضرورية وإضافة العلامة --privileged لتجنب أي أخطاء غير مسموح بها عند محاولة فتح حلقة مفاتيح النظام.
فيما يلي نص كامل لتثبيت حلقة المفاتيح على حاوية Ubuntu 18:04:
docker run -it -d --privileged ubuntu:18.04
$ apt-احصل على التحديث
$ apt install -y gnome-keyring python3-venv python3-dev
$ python3 -m venv venv
$ source venv/bin/activate # source بيئة افتراضية لتجنب تلويث نظامك
تثبيت $ pip3 - ترقية النقطة
$ pip3 تثبيت حلقة المفاتيح
$ dbus-run-session -- sh # هذا سينقلك إلى غلاف D-bus جديد
$ صدى 'somecredstorepass' | gnome-keyring-daemon --unlock # فتح حلقة مفاتيح النظام
$ بيثون
>>> حلقة مفاتيح مستوردة
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring كائن في 0x7f9b9c971ba8>
>>> keyring.set_password("النظام"، "اسم المستخدم"، "كلمة المرور")
>>> keyring.get_password("النظام"، "اسم المستخدم")
'كلمة المرور'
تحتوي مكتبة keyring lib على بعض الوظائف:
get_keyring() : إرجاع تطبيق keyring المحمل حاليًا.get_password(service, username) : إرجاع كلمة المرور المخزنة في حلقة المفاتيح النشطة. إذا كانت كلمة المرور غير موجودة، فسيتم إرجاعها بلا.get_credential(service, username) : قم بإرجاع كائن بيانات الاعتماد المخزن في حلقة المفاتيح النشطة. يحتوي هذا الكائن على سمات username وكلمة password على الأقل للخدمة المحددة، حيث قد يكون username الذي تم إرجاعه مختلفًا عن الوسيطة.set_password(service, username, password) : قم بتخزين كلمة المرور في حلقة المفاتيح.delete_password(service, username) : حذف كلمة المرور المخزنة في حلقة المفاتيح. إذا كانت كلمة المرور غير موجودة، فسيؤدي ذلك إلى ظهور استثناء. وفي جميع الأحوال، يجب أن تكون المعلمات ( service ، username ، password ) نص Unicode.
تثير مكتبة keyring الاستثناءات التالية:
keyring.errors.KeyringError : فئة الخطأ الأساسية لجميع الاستثناءات في keyring lib.keyring.errors.InitError : يُثار عندما لا يمكن تهيئة حلقة المفاتيح.keyring.errors.PasswordSetError : يتم رفعه عندما لا يمكن تعيين كلمة المرور في حلقة المفاتيح.keyring.errors.PasswordDeleteError : يظهر عندما لا يمكن حذف كلمة المرور في حلقة المفاتيح. Python keyring lib هو مشروع مجتمعي مفتوح ويرحب بشدة بالمساهمين.
قد يكون لكل واجهة خلفية مدمجة اعتبارات أمنية يجب فهمها قبل استخدام هذه المكتبة. يتم تشجيع مؤلفي الأدوات أو المكتبات التي تستخدم keyring على مراعاة هذه المخاوف.
كما هو الحال مع أي قائمة من المخاوف الأمنية المعروفة، هذه القائمة ليست شاملة. يمكن إضافة قضايا إضافية حسب الحاجة.
keyring من نفس Python القابل للتنفيذ دون أن يطالب نظام التشغيل المستخدم بكلمة مرور. لجعل أي سر محدد يطالب بكلمة مرور في كل مرة يتم الوصول إليها، حدد موقع الاعتماد باستخدام تطبيق Keychain Access ، وفي إعدادات Access Control ، قم بإزالة Python من قائمة التطبيقات المسموح بها.يستخدم هذا المشروع الإصدارات الآلية والتكامل المستمر. سير العمل البسيط هو وضع علامة على الالتزام ودفعه إلى Github. إذا اجتاز الاختبارات في CI، فسيتم نشره تلقائيًا إلى PyPI.
أشياء أخرى يجب مراعاتها عند إصدار الإصدار:
يتم تشغيل الاختبارات بشكل مستمر في Github Actions.
لتشغيل الاختبارات محليًا، قم بتثبيت واستدعاء tox.
المشروع كان مبنياً على فكرة طارق زيادة في هذا المنشور. نفذ كانغ تشانغ هذا المشروع في البداية كمشروع Google Summer of Code، وقام طارق بإرشاد كانغ في هذا المشروع.
متاح كجزء من اشتراك Tidelift.
يعمل هذا المشروع والمشرفون على آلاف الحزم الأخرى مع Tidelift لتقديم اشتراك مؤسسي واحد يغطي جميع المصادر المفتوحة التي تستخدمها.
يتعلم أكثر.
