encrypted-keyring 0.1.0

Encrypted file-based keyring storage with a small command line interface.

keyring

Python-Paket für verschlüsselte Keyring-Dateien mit kleiner CLI und installierbarem Konsolenbefehl.

Das Projekt wird auf PyPI als encrypted-keyring veröffentlicht. Der Python-Import bleibt keyring.

Status

Der aktuelle Stand des Repos ist:

• als Python-Paket importierbar
• als CLI über python3 -m keyring nutzbar
• als installierter Befehl encrypted-keyring verfügbar
• über shell-alias.sh zusätzlich als keyring aliasierbar
• mit automatisierten Tests unter tests/ abgesichert
• auf PyPI vorbereitet über pyproject.toml

Kurz gesagt: Die Grundlage für eine veröffentlichte, installierbare Python-Bibliothek ist vorhanden, der Code ist als kleines Werkzeug direkt verwendbar, und die wichtigsten Pfade sind dokumentiert und getestet.

Was das Paket macht

Dieses Repository stellt eine einfache, dateibasierte Geheimnisverwaltung bereit:

• Ein Keyring-Objekt zum Speichern, Lesen, Aktualisieren und Löschen von Einträgen
• Eine Kryptoschicht für die Ableitung von Schlüsseln und die Verschlüsselung der gespeicherten Daten
• Eine kleine Kommandozeilenanwendung für direkte Nutzung ohne eigenes Skript
• Eine Paketkonfiguration über pyproject.toml, damit das Projekt als echtes Python-Paket gebaut und veröffentlicht werden kann

Die Daten werden lokal in einer Datei gespeichert, verschlüsselt abgelegt und mit einem Master-Passwort geöffnet.

Paket- und Importnamen

Wichtig ist die Unterscheidung zwischen Distribution und Import:

• PyPI-Name / Distribution: encrypted-keyring
• Python-Import: keyring
• Installierter CLI-Befehl: encrypted-keyring
• Optionaler Shell-Alias aus diesem Repo: keyring

Das ist absichtlich so gewählt, weil der Name keyring auf PyPI bereits stark belegt ist.

Voraussetzungen

Das Projekt benötigt:

• Python 3.10 oder neuer
• cryptography zur Schlüsselableitung und Verschlüsselung

Die Laufzeitabhängigkeit ist in pyproject.toml beschrieben. Zusätzlich liegt requirements.txt als einfache manuelle Liste im Repo.

Installation

Aus dem Repository für Entwicklung

Für eine lokale Entwicklungsumgebung:

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Das installiert:

• das Paket im Editable-Modus
• die Laufzeitabhängigkeit cryptography
• die Entwicklungswerkzeuge aus dem dev-Extra

Als reguläre Installation

Wenn das Paket später von PyPI installiert wird:

pip install encrypted-keyring

Schnellstart

Ein einfaches Beispiel für die Nutzung als Modul:

from pathlib import Path

from keyring import Keyring

ring = Keyring(path=Path("keyring.dat"), password="mein-master-passwort")
ring.put(
    "github",
    user="alice",
    password="geheim",
    description="Privates Konto",
)

print(ring.names())
print(ring.get("github"))

Ausgabe und Verhalten hängen natürlich von deinem Inhalt ab, aber der typische Ablauf ist:

1. Keyring-Datei öffnen oder anlegen
2. Eintrag speichern
3. Eintrag wieder lesen
4. Einträge bei Bedarf löschen

Nutzung als Modul

keyring exportiert die zentrale Klasse Keyring direkt auf Paket-Ebene:

from keyring import Keyring

API-Übersicht

• Keyring(path, password) öffnet oder erstellt eine Keyring-Datei
• names() liefert eine Liste aller gespeicherten Eintragsnamen
• get(name) liest einen Eintrag als dict oder gibt None zurück
• put(name, user=None, password=None, description=None, overwrite=False) speichert einen Eintrag
• delete(name) entfernt einen Eintrag

Typisches Muster

from pathlib import Path

from keyring import Keyring

ring = Keyring(path=Path("keyring.dat"), password="master")

if "github" not in ring.names():
    ring.put(
        "github",
        user="alice",
        password="geheim",
        description="Privates Konto",
    )

entry = ring.get("github")
if entry is not None:
    print(entry["user"])
    print(entry["password"])
    print(entry["description"])

Verhalten von put

Beim Speichern eines neuen Eintrags:

• wird ein zufälliger interner Schlüssel erzeugt
• werden user, password und description jeweils separat verschlüsselt
• wird der interne Schlüssel selbst mit dem Master-Passwort verschlüsselt und separat abgelegt

Das bedeutet: Der eigentliche Inhalt eines Eintrags ist nicht direkt mit demselben Schlüssel wie die Datei selbst verschlüsselt.

Kleine Anwendung

Die CLI ist für direkte Benutzung gedacht und arbeitet mit derselben Keyring-Datei wie das Modul.

Der Einstieg läuft über:

python3 -m keyring --help

Standardmäßig verwendet die CLI die Datei keyring.dat im aktuellen Arbeitsverzeichnis.

Globale Optionen

• -f, --file: Pfad zur Keyring-Datei
• -p, --password: Master-Passwort für die Datei

Wenn --password fehlt, wird es interaktiv abgefragt.

Befehle

list

Listet alle gespeicherten Einträge auf.

python3 -m keyring -p "mein-master-passwort" list

show

Zeigt einen einzelnen Eintrag an.

python3 -m keyring -p "mein-master-passwort" show github

add

Legt einen Eintrag an oder ersetzt ihn mit --overwrite.

python3 -m keyring -p "mein-master-passwort" add github --user "alice" --entry-password "geheim" --description "Privates Konto"

Wenn der Eintrag bereits existiert und nicht überschrieben werden soll, bricht die CLI mit einer Fehlermeldung ab.

delete

Löscht einen gespeicherten Eintrag.

python3 -m keyring -p "mein-master-passwort" delete github

Beispielablauf

python3 -m keyring -p "master" add demo --user alice --entry-password secret --description test
python3 -m keyring -p "master" list
python3 -m keyring -p "master" show demo
python3 -m keyring -p "master" delete demo

Shell-Alias

Wenn du den installierten CLI-Befehl lieber als keyring aufrufen möchtest, kannst du das beiliegende Alias-Snippet laden:

source ./shell-alias.sh

Die Datei shell-alias.sh enthält:

alias keyring='encrypted-keyring'

Hinweis:

• Das ist ein Shell-Alias, kein Python-Import.
• Der Alias betrifft nur deine aktuelle Shell-Sitzung, solange du ihn nicht dauerhaft in deiner Shell-Startdatei einträgst.
• In einer dauerhaften Konfiguration kannst du denselben Alias zum Beispiel in ~/.bashrc oder ~/.zshrc hinterlegen.

Tests

Für das Projekt existiert eine pytest-Suite unter tests/:

• tests/test_crypto.py
• tests/test_keyring.py
• tests/test_cli.py

Die Tests decken ab:

• Verschlüsselung und Entschlüsselung mit str- und bytes-Passwörtern
• Erzeugen zufälliger Eintrags-Schlüssel
• Speichern, Laden, Löschen und Auflisten von Einträgen
• CLI-Verhalten über den main()-Einstiegspunkt

Zusätzlich sind folgende Szenarien abgedeckt:

• Erzeugen und erneutes Laden einer leeren Keyring-Datei
• Fehlverhalten bei falschem Master-Passwort
• get() und delete() bei nicht vorhandenen Einträgen
• Überschreiben und Nicht-Überschreiben bestehender Einträge
• CLI-Fehlerfälle für show, add ohne --overwrite und delete
• CLI-Hilfe über --help

Tests ausführen

python3 -m pytest -q

Falls dein System-Python extern verwaltet ist, empfiehlt sich ein virtuelles Umfeld:

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
python3 -m pytest -q

Packaging und Veröffentlichung

Die Paketdefinition liegt vollständig in pyproject.toml.

Wichtige Punkte daraus:

• Build-Backend: setuptools
• Distribution-Name: encrypted-keyring
• Konsolenbefehl: encrypted-keyring
• Python-Version: >=3.10
• Laufzeitabhängigkeit: cryptography
• Entwicklungsabhängigkeiten: build, pytest, twine

Lokales Builden

python3 -m build

Das erzeugt typischerweise:

• ein Source Distribution Archiv
• ein Wheel

Veröffentlichungsprüfung

Vor einem Upload ist ein Trockenlauf sinnvoll:

python3 -m twine check dist/*

Upload auf PyPI

Wenn du veröffentlichen willst:

python3 -m twine upload dist/*

Datenformat und Verhalten

• Die Keyring-Datei wird verschlüsselt gespeichert.
• Beim Schreiben wird eine temporäre Datei verwendet und anschließend atomar ersetzt.
• Nach dem Schreiben wird die Datei mit Berechtigung 600 versehen, damit nur der Besitzer lesen und schreiben kann.
• Die interne Struktur trennt die eigentlichen Eintragsdaten von den verschlüsselten Eintrags-Schlüsseln.
• Die Kryptoschicht akzeptiert Passwortwerte als str oder als bytes.
• Zufällige Eintrags-Schlüssel werden intern als Bytes erzeugt und verschlüsselt abgelegt.
• Die Datei keyring.dat ist eine Laufzeitdatei und gehört nicht ins Git-Repository.

Projektstruktur

• keyring/__init__.py - Paket-Exports für Keyring und Crypto
• keyring/__main__.py - CLI-Einstiegspunkt
• keyring/crypto.py - Schlüsselableitung, Verschlüsselung und Entschlüsselung
• keyring/keyring.py - Laden, Speichern und Verwalten der Keyring-Daten
• pyproject.toml - Build-, Packaging- und Test-Konfiguration
• requirements.txt - manuelle Liste der Laufzeitabhängigkeiten
• shell-alias.sh - Shell-Alias für den CLI-Befehl
• tests/ - automatisierte Tests

Veröffentlichung und Nutzung

Ein typischer Ablauf für die Weiterentwicklung ist:

1. Code ändern
2. Tests ergänzen oder anpassen
3. python3 -m pytest -q ausführen
4. python3 -m build ausführen
5. python3 -m twine check dist/* prüfen
6. Paket auf PyPI hochladen

Hinweise

• Der Python-Import bleibt keyring, auch wenn die Distribution encrypted-keyring heißt.
• Die CLI ist separat installierbar und kann über den Shell-Alias bequem auf keyring gelegt werden.
• Wenn du neue Funktionen ergänzt, sollten dazu passende Tests und eine kurze Dokumentation dazukommen.