95.1.64. pepsi-helper-auto-pay¶
drive taler-wallet-cli as the paying user
- Handbuchabschnitt:
1
95.1.64.1.1. Name¶
pepsi-helper-auto-pay - privilegierter Helper, der eine GNU-Taler-Zustellungsforderung bepreist oder bezahlt, indem er taler-wallet-cli als der richtige Benutzer ausführt.
95.1.64.1.2. Übersicht¶
pepsi-helper-auto-pay OP ( –uid N | –user NAME –wallet-db KEY ) [OP-OPTIONS]
wobei OP eines von preview/pay –uri TALER-URI [–pay-option OPT]…, balance, withdraw –amount CURRENCY:VALUE –exchange URL, push –uri TALER-URI oder pull –amount CURRENCY:VALUE [–subject TEXT] ist.
95.1.64.1.3. Beschreibung¶
pepsi-helper-auto-pay ist ein minimaler, sicherheitsgehärteter Helper, der taler-wallet-cli gegen genau ein Wallet, als genau ein Benutzer, für eine Wallet-Operation ausführt. Er existiert, damit ein vertrauenswürdiger, aber unprivilegierter Aufrufer (ein Mitglied der pepsi-wallets-Gruppe, in der Praxis pepsi-stage-auto-pay(1)) das richtige Wallet bedienen kann und sonst nichts tun kann.
Die unterstützten Operationen sind: preview (eine taler://pay/…-Forderung bepreisen, ohne zu bezahlen) und pay (eine begleichen) für die eingehende Forderungsbezahl-Rolle; sowie balance, withdraw (eine manuelle Aufladung gegen einen Exchange einrichten), push (eine eingehende taler://pay-push/…-Peer-Zahlung annehmen) und pull (eine Peer-Pull-Anfrage initiieren, die eine taler://pay-pull/…-URI erzeugt) für die Wallet-Self-Service-Rolle.
Der Helper wird setuid-root installiert, im Besitz von root:pepsi-wallets mit Modus 4750. Nur Mitglieder der pepsi-wallets-Gruppe dürfen ihn ausführen; wenn sie es tun, führt der Kernel ihn mit einer effektiven uid von root aus. Der Helper:
löst das Zielkonto auf und, im shared-Modus, den Wallet-Datenbank-Pfad innerhalb des Homes dieses Kontos, gebaut aus dem validierten KEY (der Pfad kann daher nie aus dem Home ausbrechen);
gibt Privilegien vollständig und unwiderruflich an den Zielbenutzer ab: Er installiert die ergänzenden Gruppen des Benutzers, setzt dann die gid, dann die uid (real, effektiv und gespeichert) und prüft, dass root nicht wiedererlangt werden kann. Er verweigert uid
0und das Loginroot. Im local-user-Modus verweigert er außerdem jede uid unterhalb von/etc/login.defsUID_MIN(1000, wenn diese Datei nicht gelesen werden kann), weil dort ein echter Empfänger erwartet wird. Der shared-Modus ist davon ausgenommen, denn sein Ziel ist das DienstkontoWALLET_USER, das der Betreiber konfiguriert hat (z. B.pepsi-wallets, typischerweise mit einer niedrigen uid). Dort muss stattdessen die primäre Gruppe des Kontos die Gruppe der ausführbaren Datei dieses Helpers sein (pepsi-wallets); diese Gruppe hat kein Systemkonto. Wie pepsi-helper-dot-forward(1) und pepsi-helper-maildir-writer(1) legt der Helper root vollständig ab;führt
taler-wallet-clifür die angeforderte Operation aus (im shared-Modus mit--wallet-db=…). Das Programm ist immer das systemweite, das beim Bauen des Helpers festgelegt wurde (standardmäßig/usr/bin/taler-wallet-cli;make TALER_WALLET_CLI=…oder./configure --with-taler-wallet-cli=…). Der Helper führt es erst aus, nachdem er geprüft hat, dass es und jedes Verzeichnis darüber root gehören und für niemanden sonst schreibbar sind. Er übernimmt es nie von der Befehlszeile, aus der Umgebung oder aus der Konfiguration. Seine Umgebung wird von Grund auf gebaut, nicht gefiltert: Das Kind erhält nurHOME,USER/LOGNAME(das Zielkonto), einen festenPATHundSHELLund nichts von dem, was der Aufrufer übergeben hat. Zu diesem Zeitpunkt sind die Privilegien bereits abgegeben, sodass der dynamische LaderLD_PRELOAD/LD_AUDITwieder beachtet, und das Wallet ist ein Node.js-Programm, dasNODE_OPTIONS/NODE_PATHbeachtet. Der Aufrufer wählt jede Variable in seiner eigenen Umgebung. Würde der Helper nur bekannt schädliche Namen entfernen, könnte ein Aufrufer „das Wallet als alice ausführen“ immer noch in „den Code des Aufrufers als alice ausführen“ verwandeln. Genau diese Rechteausweitung soll der Helper verhindern. Der Aufrufer könnte außerdem den Exchange-Verkehr des Wallets umleiten (https_proxy/SSL_CERT_FILE). Im shared-Modus wird das Wallet-Datenbank-Verzeichnis~NAME/walletsmit Modus0700angelegt, falls es fehlt.previewfragt wallet-core nach dem Vorschlag (api preparePayForUriV2) und liest den Preis aus den Vertragsbedingungen. Mithandle-urilässt sich kein Preis ermitteln: Ohne--yesbleibt es an einer Bestätigungsabfrage stehen, die nicht bei EOF endet, und es gibt ohnehin keinen Preis aus.payführthandle-uri --choice-index 0 --yessamt etwaiger zusätzlicher--pay-option-Argumente aus und läuft bis zum Abschluss (ein Vertrag der Version 1 bietet eine Liste vonchoicesund kann erst bezahlt werden, wenn eine davon benannt ist; die erste ist die, deren Preispreviewermittelt hat).pushbenötigt zwei Wallet-Befehle:preparePeerPushCreditvon wallet-core (api), um die eingehende Zahlung zu erfassen und ihre Transaktions-ID zu erhalten, danncontinue-tx --yes --wait, um sie anzunehmen. (Bei einer solchen URI fragthandle-uriunabhängig von--yesnach einer Bestätigung und scheitert ohne Terminal.)pullführtpeer-requestaus,balanceundwithdrawdie gleichnamigen Unterbefehle; jeder berichtet sein Ergebnis (die Pay-Pull-URI, den Guthabentext oder die Überweisungsanweisungen für die Abhebung). Nur die genauentaler-wallet-cli-Unterbefehle hängen von der Wallet-Version ab, und sie stehen allein im Helper.
Beide Peer-Operationen warten auf die Task-Schleife des Wallets. peer-request kehrt zurück, sobald die Purse beim Exchange liegt; vorher ist die URI, die der Benutzer erhält, überhaupt nicht bezahlbar, und nichts anderes würde die Purse je anlegen, da ein Wallet pro Benutzer nur aufwacht, wenn sein Besitzer den nächsten Befehl schickt. Der Helper lässt ihm 60 Sekunden Zeit und meldet danach einen Fehlschlag. Auf einen angenommenen push wird gewartet, bis er abgeschlossen ist, höchstens 30 Sekunden lang, damit seine Münzen ausgegeben werden können statt ausstehend zu bleiben. Jedes Warten endet meist nach ein bis zwei Sekunden; die Grenzen greifen, wenn der Exchange nicht erreichbar ist oder zuerst eine KYC-Prüfung verlangt. Der Helper benötigt ein taler-wallet-cli mit peer-request und continue-tx (ab 1.6.46).
Wenn das Wallet für eine Self-Service-Operation eine KYC-Anforderung (Identitätsprüfung) meldet, extrahiert der Helper die KYC-URL und beendet sich mit 3, mit der URL auf der Standardausgabe, sodass die Stage dem Benutzer den Link per E-Mail schicken kann. Der Helper sucht nur dann nach KYC, wenn die Operation kein eigenes Ergebnis erzeugt hat: Eine erfolgreiche Operation wird als Erfolg gemeldet, selbst wenn die Diagnoseausgabe des Wallets irgendwo KYC erwähnt, und die URL wird dem Text entnommen, der KYC erwähnt, statt der Stelle, an der zuerst irgendeine URL auftaucht.
Der Aufrufer wählt eines von zwei Kontomodellen. Mit –uid gibt der Helper seine Privilegien an diese lokale uid ab und verwendet das Standard-Wallet dieses Benutzers (WALLET_MODE = local-user in pepsi-stage-auto-pay(1)). Mit –user und –wallet-db gibt er sie an das genannte gemeinsame Konto ab (Standardwert pepsi-wallets) und richtet das Wallet auf ~NAME/wallets/KEY.sqlite3 (WALLET_MODE = shared). Ein Wallet, das unter dem Namen KEY.json liegt, wird nicht migriert; das aktuelle taler-wallet-cli öffnet dieses Format nicht mehr. Der Helper warnt dann auf der Standardfehlerausgabe und legt daneben ein neues Wallet an.
Dieses Programm ist nicht dafür gedacht, von Hand ausgeführt zu werden; pepsi-stage-auto-pay(1) ruft es auf. Es ist hier wegen seiner privilegierten Installation dokumentiert.
95.1.64.1.4. Optionen¶
- preview | pay | balance | withdraw | push | pull
Die Operation.
previewgibt den Preis einer Forderung aus, ohne zu bezahlen;paybegleicht sie;balancegibt das Wallet-Guthaben aus;withdrawrichtet eine manuelle Aufladung ein und gibt die Überweisungsanweisungen aus;pushnimmt eine eingehende Peer-Zahlung an;pullinitiiert eine Peer-Pull-Anfrage und gibt die resultierende URI aus.- –uri TALER-URI
Die
taler://pay/…- (preview/pay) odertaler://pay-push/…-URI (push), mit der gearbeitet werden soll. Für diese Operationen erforderlich. Der Helper prüft sie hier, an der privilegierten Grenze, erneut:preview/payverweigern alles, was keinetaler://pay/-URI ist,pushverweigert alles, was keintaler://ist, und jede URI wird rundweg abgelehnt, wenn sie ein Zeichen außerhalb des Repertoires von RFC 3986 enthält (sodass Anführungszeichen, Backslashes und Leerraum nie das Wallet erreichen können).- –amount CURRENCY:VALUE
Der GNU-Taler-Betrag, erforderlich für
withdrawundpull.- –exchange URL
Die Exchange-Basis-URL für ein manuelles
withdraw(erforderlich).- –subject TEXT
Ein optionaler Zahlungsbetreff bzw. eine optionale Zusammenfassung für
pull.- –uid N
Local-user-Modus: Gibt die Privilegien an uid N ab und verwendet das Standard-Wallet dieses Benutzers. Schließt sich mit –user gegenseitig aus.
- –user NAME –wallet-db KEY
Shared-Modus: Gibt die Privilegien an das Konto NAME ab und verwendet die Wallet-Datenbank, die durch den undurchsichtigen, validierten KEY unterhalb des Homes dieses Kontos benannt wird. Beide sind zusammen erforderlich.
- –wallet-cli PATH
Wird mit einem Fehler abgelehnt. Welches Programm als ein anderes Konto läuft, ist zur Build-Zeit festgelegt. Sonst könnte jeder Aufrufer, der es benennen kann, also jeder Code, der als Konto
pepsiläuft, ein Programm seiner Wahl als dieses Konto ausführen.- –pay-option OPT
Ein zusätzliches Argument, das an den
pay-Aufruf angehängt wird (wiederholbar; keines ist nötig, dahandle-uribereits wartet, bis die Zahlung einen Endzustand erreicht);--yeswirdpayebenfalls hinzugefügt, da ein aus einer Stage heraus laufender Helper niemanden fragen kann.Beides gilt nicht für push, das gar kein
handle-uri-Aufruf ist, sondern ein Ablauf aus zwei Befehlen,preparePeerPushCredit/continue-tx:continue-txlehnt diese Flags rundweg ab, und es wartet selbst auf die Gutschrift. Auf diesem Pfad werden die Optionen angenommen und ignoriert, sodass einWALLET_PAY_OPTIONS, das für ein Self-Service-pushgesetzt ist, keine Wirkung hat.
95.1.64.1.5. Exit-Status¶
- 0
Erfolg. Bei
previewsteht der vorgeschlagene Betrag auf der Standardausgabe; beibalance,withdrawundpullsteht der Berichtstext auf der Standardausgabe; beipayundpushist die Standardausgabe leer.- 2
Die Operation schlug fehl (ungültige Argumente, nicht setuid-root, ein verweigertes Konto, der Preis konnte nicht gelesen werden, oder die Wallet-Operation schlug fehl). Eine menschenlesbare Diagnose wird auf die Standardausgabe und die Standardfehlerausgabe geschrieben.
- 3
Das Wallet erfordert KYC (Identitätsverifikation); die KYC-URL steht auf der Standardausgabe.
95.1.64.1.6. Sicherheit¶
Der Helper verrichtet bewusst keine Arbeit mit Konfiguration, Datenbank oder Protokollen. Seine einzige privilegierte Aktion ist, vor dem Ausführen des Wallets zum Zielbenutzer zu werden; er weigert sich, als root zu handeln, und prüft nach der Abgabe der Privilegien, dass root nicht wiedererlangt werden kann. Der Zugriff auf ihn ist durch die pepsi-wallets-Gruppe beschränkt, die dem Aufrufer über das SGID-Bit von pepsi-stage-auto-pay(1) gewährt wird und sonst niemandem. Das Kapitel Security model des Handbuchs (The privilege split) führt jedes Programm auf, das ein setuid- oder setgid-Bit trägt; sein Kapitel Threat model (der Abschnitt zum lokalen Benutzer) legt dar, wozu die Helper gebracht werden dürfen und wozu nicht.
95.1.64.1.7. Siehe auch¶
pepsi-stage-auto-pay(1), pepsi-stage-anti-spam(1), pepsi-helper-dot-forward(1), pepsi-dispatch(1), pepsi.conf(5)
95.1.64.1.8. Fehler¶
Melden Sie Fehler an den Pepsi-Issue-Tracker.