85.1.58. pepsi-helper-auto-pay

drive taler-wallet-cli as the paying user

Handbuchabschnitt:

1

85.1.58.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.

85.1.58.1.2. Übersicht

pepsi-helper-auto-pay OP ( –uid N | –user NAME –wallet-db KEY ) [–wallet-cli PATH] [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.

85.1.58.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 passende Wallet ansteuern kann — und nichts anderes.

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:

  1. 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);

  2. gibt Privilegien vollständig und unwiderruflich an den Zielbenutzer ab — installiert die ergänzenden Gruppen des Benutzers, setzt dann die gid, dann die uid (real+effektiv+gespeichert), und verifiziert, dass root nicht wiedererlangt werden kann — und verweigert uid 0 sowie das Login root. Im local-user-Modus verweigert er zusätzlich jede uid unterhalb von /etc/login.defs UID_MIN (1000, wenn diese Datei nicht gelesen werden kann; dort wird ein echter Empfänger erwartet); der shared-Modus ist ausgenommen, da sein Ziel das vom Operator konfigurierte WALLET_USER-Dienstkonto ist (z. B. pepsi-wallets, typischerweise eine niedrige uid). (Wie pepsi-helper-dot-forward(1) und pepsi-helper-maildir-writer(1) wirft er root vollständig ab.)

  3. führt taler-wallet-cli aus — optional mit --wallet-db=… — für die angeforderte Operation, mit einer von Grund auf gebauten, nicht gefilterten Umgebung: Das Kind erhält nur HOME, USER/LOGNAME (das Zielkonto), einen festen PATH und SHELL und nichts von dem, was der Aufrufer übergeben hat. Die Privilegien sind bereits abgegeben, sodass der dynamische Lader LD_PRELOAD/LD_AUDIT wieder beachtet, und das Wallet ist ein Node.js-Programm, das NODE_OPTIONS/NODE_PATH beachtet; jede Variable in der Umgebung des Aufrufers ist vom Aufrufer gewählt, sodass das Abziehen bekannt schlechter Namen „das Wallet als alice ausführen“ als „den Code des Aufrufers als alice ausführen“ erreichbar ließe — genau die Rechteausweitung, zu deren Verhinderung dieser Helper existiert — und dem Aufrufer außerdem erlaubte, den Exchange-Verkehr des Wallets umzuleiten (https_proxy/SSL_CERT_FILE). Im shared-Modus wird das Wallet-Datenbank-Verzeichnis ~NAME/wallets mit Modus 0700 angelegt, falls es fehlt.

    preview fragt wallet-core nach dem Vorschlag (api preparePayForUri) und liest den Preis aus den Vertragsbedingungen — handle-uri taugt nicht zum Bepreisen, da es ohne --yes an einer Bestätigungsabfrage stehenbleibt, die nicht bei EOF endet, und ohnehin keinen Preis ausgibt. pay führt handle-uri --choice-index 0 --yes samt etwaiger zusätzlicher --pay-option-Argumente aus und läuft bis zum Abschluss (ein Vertrag der Version 1 bietet eine Liste von choices und kann erst bezahlt werden, wenn eine benannt ist; die erste ist die, die preview bepreist hat). push benötigt zwei Wallet-Befehle — p2p prepare-push-credit für die Transaktions-ID der eingehenden Zahlung, dann p2p confirm-push-credit, um sie anzunehmen (handle-uri kehrt bei einer solchen URI nicht zurück, sodass die Purse unangenommen verfiele). balance, withdraw und pull führen die entsprechenden Wallet-Unterbefehle aus und berichten deren Ergebnis (den Guthabentext, die Überweisungsanweisungen für die Abhebung oder die Pay-Pull-URI). Die genauen taler-wallet-cli-Unterbefehle sind der eine wallet-versionsabhängige Punkt, isoliert im Helper.

Nach einem pull und nach dem Annehmen eines push führt der Helper die Task-Schleife des Wallets (run-until-done) für eine begrenzte Zeit aus (30 Sekunden). p2p initiate-pull-credit erfasst die Anfrage nur lokal, und die Purse wird von dieser Schleife beim Exchange angelegt — bis sie gelaufen ist, ist die URI, die der Benutzer erhält, überhaupt nicht bezahlbar, und nichts anderes würde sie je ausführen, da ein Wallet pro Benutzer nur aufwacht, wenn sein Besitzer den nächsten Befehl schickt. Die Begrenzung existiert, weil ein Peer-Pull-Guthaben erst „fertig“ ist, wenn jemand es bezahlt hat, sodass der Befehl sonst ewig warten würde.

Wenn das Wallet für eine Self-Service-Operation eine KYC-(Identitätsverifikations-)Anforderung 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. Das wird nur in Betracht gezogen, 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 sie erwähnt, statt der Stelle, an der zuerst irgendeine URL auftaucht.

Die beiden Kontomodelle werden vom Aufrufer gewählt. 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).

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.

85.1.58.1.4. Optionen

preview | pay | balance | withdraw | push | pull

Die Operation. preview gibt den Preis einer Forderung aus, ohne zu bezahlen; pay begleicht sie; balance gibt das Wallet-Guthaben aus; withdraw richtet eine manuelle Aufladung ein und gibt die Überweisungsanweisungen aus; push nimmt eine eingehende Peer-Zahlung an; pull initiiert eine Peer-Pull-Anfrage und gibt die resultierende URI aus.

–uri TALER-URI

Die taler://pay/…- (preview/pay) oder taler://pay-push/…-URI (push), auf die gehandelt werden soll. Für diese Operationen erforderlich. Sie wird hier, an der privilegierten Kante, erneut geprüft: preview/pay verweigern alles, was keine taler://pay/-URI ist, push alles, was kein taler:// 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 withdraw und pull.

–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

Das auszuführende taler-wallet-cli-Binärprogramm (Standardwert taler-wallet-cli, aufgelöst über $PATH).

–pay-option OPT

Ein zusätzliches Argument, das an den pay-Aufruf angehängt wird (wiederholbar, z. B. --run-until-done); --yes wird pay ebenfalls 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 — p2p prepare-push-credit / confirm-push-credit: confirm-push-credit lehnt diese Flags rundweg ab, und die Task-Schleife, um die sie üblicherweise bitten, leistet die eigene Antriebsschleife des Helpers ohnehin. Auf diesem Pfad werden die Optionen angenommen und ignoriert, sodass ein für ein Self-Service-push gesetztes WALLET_PAY_OPTIONS keine Wirkung hat.

85.1.58.1.5. Exit-Status

0

Erfolg. Bei preview steht der vorgeschlagene Betrag auf der Standardausgabe; bei balance, withdraw und pull steht der Berichtstext auf der Standardausgabe; bei pay und push ist 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.

85.1.58.1.6. Sicherheit

Der Helper verrichtet bewusst keine Konfigurations-, Datenbank- oder Protokollierungsarbeit. Seine einzige privilegierte Aktion ist, vor dem Ausführen des Wallets zum Zielbenutzer zu werden; er weigert sich, als root zu handeln, und verifiziert nach der Privilegienabgabe, dass root nicht wiedererlangbar ist. 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.

85.1.58.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)

85.1.58.1.8. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.