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:

  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: 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 0 und das Login root. Im local-user-Modus verweigert er außerdem jede uid unterhalb von /etc/login.defs UID_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 Dienstkonto WALLET_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;

  3. führt taler-wallet-cli fü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 nur HOME, USER/LOGNAME (das Zielkonto), einen festen PATH und SHELL und nichts von dem, was der Aufrufer übergeben hat. Zu diesem Zeitpunkt sind die Privilegien 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. 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/wallets mit Modus 0700 angelegt, falls es fehlt.

    preview fragt wallet-core nach dem Vorschlag (api preparePayForUriV2) und liest den Preis aus den Vertragsbedingungen. Mit handle-uri lässt sich kein Preis ermitteln: Ohne --yes bleibt es an einer Bestätigungsabfrage stehen, die nicht bei EOF endet, und es gibt ohnehin keinen Preis aus. 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 davon benannt ist; die erste ist die, deren Preis preview ermittelt hat). push benötigt zwei Wallet-Befehle: preparePeerPushCredit von wallet-core (api), um die eingehende Zahlung zu erfassen und ihre Transaktions-ID zu erhalten, dann continue-tx --yes --wait, um sie anzunehmen. (Bei einer solchen URI fragt handle-uri unabhängig von --yes nach einer Bestätigung und scheitert ohne Terminal.) pull führt peer-request aus, balance und withdraw die gleichnamigen Unterbefehle; jeder berichtet sein Ergebnis (die Pay-Pull-URI, den Guthabentext oder die Überweisungsanweisungen für die Abhebung). Nur die genauen taler-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. 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), mit der gearbeitet werden soll. Für diese Operationen erforderlich. Der Helper prüft sie hier, an der privilegierten Grenze, erneut: preview/pay verweigern alles, was keine taler://pay/-URI ist, push verweigert 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

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 pepsi lä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, da handle-uri bereits wartet, bis die Zahlung einen Endzustand erreicht); --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, preparePeerPushCredit / continue-tx: continue-tx lehnt diese Flags rundweg ab, und es wartet selbst auf die Gutschrift. Auf diesem Pfad werden die Optionen angenommen und ignoriert, sodass ein WALLET_PAY_OPTIONS, das für ein Self-Service-push gesetzt ist, keine Wirkung hat.

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

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.