keyring
v25.5.0
ไลบรารี Python keyring มอบวิธีง่ายๆ ในการเข้าถึงบริการ keyring ของระบบจาก python สามารถใช้ในแอปพลิเคชันใดๆ ที่ต้องการการจัดเก็บรหัสผ่านที่ปลอดภัย
รองรับแบ็กเอนด์พวงกุญแจที่แนะนำเหล่านี้:
การใช้งานคีย์ริงอื่นๆ มีให้ใช้งานผ่านแบ็กเอนด์ของบุคคลที่สาม
บน Linux แบ็กเอนด์ KWallet อาศัย dbus-python ซึ่งไม่ได้ติดตั้งอย่างถูกต้องเสมอไปเมื่อใช้ pip (จำเป็นต้องมีการคอมไพล์) เพื่อผลลัพธ์ที่ดีที่สุด ให้ติดตั้ง 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 ดังนี้:
$ พวงกุญแจ --help $ ชื่อผู้ใช้ระบบชุดพวงกุญแจ รหัสผ่านสำหรับ 'ชื่อผู้ใช้' ใน 'ระบบ': $ keyring รับชื่อผู้ใช้ระบบ รหัสผ่าน
ฟังก์ชันบรรทัดคำสั่งยังแสดงเป็นแพ็คเกจปฏิบัติการ ซึ่งเหมาะสำหรับการเรียกใช้จาก Python ดังนี้:
$ python -m พวงกุญแจ --help $ python -m ชื่อผู้ใช้ชุดพวงกุญแจ รหัสผ่านสำหรับ 'ชื่อผู้ใช้' ใน 'ระบบ': $ python -m keyring รับชื่อผู้ใช้ระบบ รหัสผ่าน
หากติดตั้งผ่านตัวจัดการแพ็คเกจ (apt, pacman, nix, homebrew ฯลฯ) การเสร็จสิ้นเชลล์เหล่านี้อาจถูกแจกจ่ายไปพร้อมกับแพ็คเกจแล้ว (ไม่ต้องดำเนินการใดๆ)
Keyring จัดเตรียมการเติมแท็บให้สมบูรณ์หากมีการติดตั้ง completion เพิ่มเติม:
$ pip ติดตั้ง 'พวงกุญแจ [เสร็จสิ้น]'
จากนั้นสร้างการสำเร็จของเชลล์ บางอย่างเช่น:
$ keyring --print-complet bash | sudo tee /usr/share/bash-completion/completions/keyring $ keyring --print-complete zsh | sudo tee /usr/share/zsh/site-functions/_keyring $ keyring --print-complete tcsh | sudo tee /etc/profile.d/keyring.csh
หมายเหตุ : เส้นทางของ /usr/share มีไว้สำหรับ GNU/Linux เป็นหลัก สำหรับ OS อื่นๆ ให้พิจารณา:
หลังจากติดตั้งเชลล์ที่เสร็จสมบูรณ์แล้ว ให้เปิดใช้งานตามคำแนะนำที่แนะนำของเชลล์ เช่น:
. /usr/share/bash-completion/bash_completion ใน ~/.bashrcautoload -Uz compinit && compinit ปรากฏใน ~/.zshrc จากนั้น grep -w keyring ~/.zcompdump เพื่อตรวจสอบว่าพวงกุญแจปรากฏขึ้น โดยระบุว่าติดตั้งอย่างถูกต้อง lib ของ python keyring มีการนำไปใช้งานสำหรับแบ็กเอนด์หลายตัว ไลบรารีจะพยายามเลือกแบ็กเอนด์ที่เหมาะสมที่สุดสำหรับสภาพแวดล้อมปัจจุบันโดยอัตโนมัติ ผู้ใช้อาจระบุพวงกุญแจที่ต้องการในไฟล์กำหนดค่าหรือโดยการเรียกใช้ฟังก์ชัน set_keyring()
การกำหนดค่าจะถูกจัดเก็บไว้ในไฟล์ชื่อ "keyringrc.cfg" ซึ่งพบในตำแหน่งเฉพาะแพลตฟอร์ม หากต้องการทราบว่าไฟล์กำหนดค่าถูกจัดเก็บไว้ที่ใด ให้รัน keyring diagnose
หากต้องการระบุแบ็กเอนด์คีย์ริง ให้ตั้งค่าตัวเลือก ดีฟอลต์คีย์ริง เป็นพาธเต็มของคลาสสำหรับแบ็กเอนด์นั้น เช่น keyring.backends.macOS.Keyring
หากมีการระบุ เส้นทางพวงกุญแจ พวงกุญแจจะเพิ่มเส้นทางนั้นไปยังเส้นทางการค้นหาโมดูล Python ก่อนที่จะโหลดแบ็กเอนด์
ตัวอย่างเช่น การกำหนดค่านี้อาจใช้เพื่อโหลด SimpleKeyring จากโมดูล simplekeyring ในไดเร็กทอรี ./demo (ไม่ได้ใช้งาน):
[แบ็กเอนด์] default-keyring=simplekeyring.SimpleKeyring พวงกุญแจเส้นทาง = การสาธิต
นอกเหนือจากแบ็กเอนด์ที่ได้รับจากแพ็คเกจคีย์ริงหลักสำหรับกรณีการใช้งานทั่วไปและปลอดภัยที่สุดแล้ว ยังมีการใช้งานแบ็กเอนด์คีย์ริงเพิ่มเติมสำหรับกรณีการใช้งานอื่นๆ เพียงติดตั้งเพื่อให้พร้อมใช้งาน:
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
def set_password (ตัวเอง, ชื่อบริการ, ชื่อผู้ใช้, รหัสผ่าน):
ผ่าน
def get_password (ตัวเอง, ชื่อบริการ, ชื่อผู้ใช้):
ส่งคืน "รหัสผ่านจาก TestKeyring"
def Delete_password (ตัวเอง, ชื่อบริการ, ชื่อผู้ใช้):
ผ่าน
# ตั้งค่าพวงกุญแจสำหรับ keyring lib
keyring.set_keyring (ทดสอบพวงกุญแจ ())
# เรียกใช้ keyring lib
พยายาม:
keyring.set_password("บริการสาธิต", "tarek", "passexample")
print("เก็บรหัสผ่านเรียบร้อยแล้ว")
ยกเว้น keyring.errors.PasswordSetError:
print("ไม่สามารถจัดเก็บรหัสผ่าน")
พิมพ์ ("รหัสผ่าน", keyring.get_password ("บริการสาธิต", "tarek"))
ในหลายกรณี การถอนการติดตั้งพวงกุญแจอาจไม่จำเป็นเลย โดยเฉพาะอย่างยิ่งบน Windows และ macOS พฤติกรรมของพวงกุญแจมักจะลดลง ซึ่งหมายความว่ามันจะส่งคืนค่าว่างให้กับผู้โทร ทำให้ผู้โทรถอยกลับไปใช้พฤติกรรมอื่นได้
ในบางกรณี ลักษณะการทำงานเริ่มต้นของพวงกุญแจนั้นไม่เป็นที่พึงปรารถนา และควรปิดการใช้งานลักษณะการทำงานของพวงกุญแจไปเลยจะดีกว่า มีกลไกหลายประการในการปิดใช้งานพวงกุญแจ:
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring ในสภาพแวดล้อม และแบ็กเอนด์ Null (เสื่อมลง) จะถูกนำมาใช้ วิธีการนี้ส่งผลต่อการใช้งาน Keyring ทั้งหมดที่มีการตั้งค่าตัวแปรนั้นkeyring --disable หรือ python -m keyring --disable วิธีการนี้ส่งผลต่อการใช้พวงกุญแจทั้งหมดสำหรับผู้ใช้รายนั้น พวงกุญแจเป็นกลไกในการปรับเปลี่ยนพฤติกรรมของพวงกุญแจผ่านตัวแปรสภาพแวดล้อม แบ็กเอนด์แต่ละรายการจะใช้ KeyringBackend.set_properties_from_env ซึ่งเมื่อเรียกใช้จะค้นหาตัวแปรสภาพแวดล้อมทั้งหมดที่ขึ้นต้นด้วย KEYRING_PROPERTY_{NAME} และจะตั้งค่าคุณสมบัติสำหรับ {NAME.lower()} แต่ละรายการบนพวงกุญแจ วิธีการนี้ถูกเรียกใช้ระหว่างการกำหนดค่าเริ่มต้นสำหรับพวงกุญแจเริ่มต้น/ที่กำหนดค่าไว้
กลไกนี้อาจใช้เพื่อตั้งค่าที่เป็นประโยชน์บนพวงกุญแจต่างๆ ได้แก่:
ต่อไปนี้เป็นบันทึกฉบับสมบูรณ์สำหรับการติดตั้งพวงกุญแจในสภาพแวดล้อมเสมือนบน Ubuntu 16.04 ไม่มีการใช้ไฟล์กำหนดค่า:
$ sudo apt ติดตั้ง python3-venv libdbus-glib-1-dev
$ซีดี/tmp
$ pyvenv py3
$ แหล่งที่มา py3/bin/activate
$ pip ติดตั้ง -U pip
$ pip ติดตั้งหน่วยเก็บความลับ dbus-python
$ pip ติดตั้งพวงกุญแจ
$ หลาม
>>> พวงกุญแจนำเข้า
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring วัตถุที่ 0x7f9b9c971ba8>
>>> keyring.set_password("ระบบ", "ชื่อผู้ใช้", "รหัสผ่าน")
>>> keyring.get_password("ระบบ", "ชื่อผู้ใช้")
'รหัสผ่าน'
คุณสามารถใช้แบ็คเอนด์ SecretService บนระบบ Linux ที่ไม่มีเซิร์ฟเวอร์ X11 ได้ (ต้องใช้ D-Bus เท่านั้น) ในกรณีนี้:
ติดตั้งภูตพวงกุญแจ GNOME
เริ่มเซสชัน D-Bus เช่น run dbus-run-session -- sh และรันคำสั่งต่อไปนี้ภายในเชลล์นั้น
เรียกใช้ gnome-keyring-daemon ด้วยตัวเลือก --unlock คำอธิบายของตัวเลือกนั้นบอกว่า:
อ่านรหัสผ่านจาก stdin และใช้เพื่อปลดล็อกคีย์การเข้าสู่ระบบหรือสร้างรหัสผ่านหากไม่มีคีย์การเข้าสู่ระบบ
เมื่อคำสั่งนั้นเริ่มทำงาน ให้ป้อนรหัสผ่านใน stdin แล้วกด Ctrl+D (สิ้นสุดข้อมูล) หลังจากนั้น daemon จะแยกเข้าสู่พื้นหลัง (ใช้ตัวเลือก --foreground เพื่อบล็อก)
ตอนนี้คุณสามารถใช้แบ็กเอนด์ SecretService ของ Keyring ได้แล้ว อย่าลืมรันแอปพลิเคชันของคุณในเซสชัน D-Bus เดียวกันกับ daemon
คุณสามารถใช้พวงกุญแจกับแบ็กเอนด์ SecretService ในคอนเทนเนอร์ Docker ได้เช่นกัน สิ่งที่คุณต้องทำคือติดตั้งการพึ่งพาที่จำเป็นและเพิ่มแฟล็ก --privileged เพื่อหลีกเลี่ยงข้อผิดพลาดการดำเนินการที่ไม่ได้รับอนุญาตเมื่อพยายามปลดล็อกพวงกุญแจของระบบ
ต่อไปนี้เป็นการถอดเสียงฉบับสมบูรณ์สำหรับการติดตั้งพวงกุญแจบนคอนเทนเนอร์ Ubuntu 18:04:
นักเทียบท่า run -it -d --ubuntu สิทธิพิเศษ: 18.04
$ apt-get อัปเดต
$ apt ติดตั้ง -y gnome-keyring python3-venv python3-dev
$ python3 -m เวนวี เวนวี
$ source venv/bin/activate # แหล่งที่มาของสภาพแวดล้อมเสมือนเพื่อหลีกเลี่ยงมลพิษในระบบของคุณ
ติดตั้ง $ pip3 -- อัปเกรด 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("ระบบ", "ชื่อผู้ใช้")
'รหัสผ่าน'
keyring lib มีฟังก์ชันบางอย่าง:
get_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 lib ทำให้เกิดข้อยกเว้นต่อไปนี้:
keyring.errors.KeyringError : คลาสข้อผิดพลาดพื้นฐานสำหรับข้อยกเว้นทั้งหมดใน keyring libkeyring.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
โครงการนี้อิงตามแนวคิดของ Tarek Ziade ในโพสต์นี้ ในตอนแรก Kang Zhang ดำเนินการดังกล่าวในฐานะโปรเจ็กต์ Google Summer of Code และ Tarek ให้คำปรึกษาแก่ Kang ในโครงการนี้
มีให้เป็นส่วนหนึ่งของการสมัครสมาชิก Tidelift
โปรเจ็กต์นี้และผู้ดูแลแพ็คเกจอื่นๆ นับพันรายการกำลังทำงานร่วมกับ Tidelift เพื่อมอบการสมัครสมาชิกระดับองค์กรหนึ่งรายการที่ครอบคลุมโอเพ่นซอร์สทั้งหมดที่คุณใช้
เรียนรู้เพิ่มเติม
