95.1.64. pepsi-helper-auto-pay¶
drive taler-wallet-cli as the paying user
- Manual section:
1
95.1.64.1.1. Name¶
pepsi-helper-auto-pay - privileged helper that prices or pays a GNU Taler
delivery demand by running taler-wallet-cli as the right user.
95.1.64.1.2. Synopsis¶
pepsi-helper-auto-pay OP ( –uid N | –user NAME –wallet-db KEY ) [OP-OPTIONS]
where OP is one of preview/pay –uri TALER-URI [–pay-option OPT]…, balance, withdraw –amount CURRENCY:VALUE –exchange URL, push –uri TALER-URI, or pull –amount CURRENCY:VALUE [–subject TEXT].
95.1.64.1.3. Description¶
pepsi-helper-auto-pay is a minimal, security-hardened helper that runs
taler-wallet-cli against exactly one wallet, as exactly one user, for one wallet
operation. It exists so that a trusted but unprivileged caller (a member of the
pepsi-wallets group, in practice pepsi-stage-auto-pay(1)) can operate
the right wallet, and do nothing else.
The supported operations are: preview (price a taler://pay/… demand without
paying) and pay (settle one) for the inbound demand-paying role; and balance,
withdraw (set up a manual top-up against an exchange), push (accept an
incoming taler://pay-push/… peer payment) and pull (initiate a peer pull,
producing a taler://pay-pull/… URI) for the wallet self-service role.
The helper is installed setuid-root, owned root:pepsi-wallets with mode
4750. Only members of the pepsi-wallets group may execute it; when they
do, the kernel runs it with an effective uid of root. The helper then:
resolves the target account and, in shared mode, the wallet-database path inside that account’s home built from the validated KEY (the path can therefore never escape the home);
drops privilege to the target user fully and irreversibly: it installs the user’s supplementary groups, then sets the gid, then the uid (real, effective and saved), and verifies that root cannot be regained. It refuses uid
0and the loginroot. In local-user mode it also refuses any uid below/etc/login.defsUID_MIN(1000 when that file cannot be read), because a real recipient is expected there. Shared mode is exempt, since its target is theWALLET_USERservice account that the operator configured (e.g.pepsi-wallets, typically with a low uid). There, the account’s primary group must instead be the group of this helper’s executable (pepsi-wallets), which no system account has. Like pepsi-helper-dot-forward(1) and pepsi-helper-maildir-writer(1), the helper sheds root completely;execs
taler-wallet-clifor the requested operation (in shared mode with--wallet-db=…). The program is always the system-wide one that was fixed when the helper was built (/usr/bin/taler-wallet-cliby default;make TALER_WALLET_CLI=…or./configure --with-taler-wallet-cli=…). The helper runs it only after checking that it and every directory above it are owned by root and writable by nobody else, and never takes it from the command line, the environment or the configuration. Its environment is built from scratch, not filtered: the child gets onlyHOME,USER/LOGNAME(the target account), a fixedPATHandSHELL, and nothing that the caller passed in. Privilege has already been dropped at that point, so the dynamic loader honoursLD_PRELOAD/LD_AUDITagain, and the wallet is a Node.js program that honoursNODE_OPTIONS/NODE_PATH. The caller chooses every variable in its own environment. If the helper only removed known-bad names, a caller could still turn “run the wallet as alice” into “run the caller’s code as alice”, which is exactly the escalation that this helper exists to prevent. The caller could also redirect the wallet’s exchange traffic (https_proxy/SSL_CERT_FILE). In shared mode the wallet-database directory~NAME/walletsis created mode0700if absent.previewasks wallet-core for the proposal (api preparePayForUriV2) and reads the price from the contract terms.handle-uricannot be used to quote a price: without--yesit stops at a confirmation prompt that does not end on EOF, and it prints no price anyway.payrunshandle-uri --choice-index 0 --yesplus any extra--pay-optionarguments and runs to completion (a version-1 contract offers a list ofchoicesand cannot be paid until one is named; the first is the one thatpreviewpriced).pushtakes two wallet commands: wallet-core’spreparePeerPushCredit(api) to record the incoming payment and get its transaction id, thencontinue-tx --yes --waitto accept it. (For such a URIhandle-uriasks for confirmation whatever--yessays, and fails without a terminal.)pullrunspeer-request, andbalanceandwithdrawthe subcommands of those names; each reports its result (the pay-pull URI, the balance text, or the withdrawal wire instructions). The exacttaler-wallet-clisubcommands are the only part that depends on the wallet version, and they are confined to the helper.
Both peer operations wait for the wallet’s task loop. peer-request returns
once the purse is at the exchange; before that, the URI that the user receives
is not payable at all, and nothing else would ever create the purse, since a
per-user wallet only wakes up when its owner sends the next command. The helper
gives it 60 seconds and reports a failure after that. An accepted push is
waited for until it is final, at most 30 seconds, so that its coins are
spendable rather than pending. Each wait usually ends within a second or two;
the limits apply when the exchange is unreachable or asks for KYC first. The
helper needs a taler-wallet-cli with peer-request and continue-tx
(1.6.46 and later).
If the wallet reports a KYC (identity verification) requirement for a self-service operation, the helper extracts the KYC URL and exits 3 with the URL on standard output, so the stage can e-mail the link to the user. The helper looks for KYC only when the operation produced no result of its own: an operation that succeeded is reported as a success even if the wallet’s diagnostic output mentions KYC somewhere, and the URL is taken from the text that mentions it rather than from wherever a URL first appears.
The caller selects one of two account models. With –uid the helper drops
to that local uid and uses that user’s default wallet (WALLET_MODE = local-user
in pepsi-stage-auto-pay(1)). With –user and –wallet-db it drops to
the named shared account (default pepsi-wallets) and points the wallet at
~NAME/wallets/KEY.sqlite3 (WALLET_MODE = shared). A wallet left under
the name KEY.json, a format that the current taler-wallet-cli no longer
opens, is not migrated: the helper warns on standard error and starts a new
wallet beside it.
This program is not meant to be run by hand; pepsi-stage-auto-pay(1) invokes it. It is documented here because of its privileged installation.
95.1.64.1.4. Options¶
- preview | pay | balance | withdraw | push | pull
The operation.
previewprints a demand’s price without paying;paysettles it;balanceprints the wallet balance;withdrawsets up a manual top-up and prints the wire instructions;pushaccepts an incoming peer payment;pullinitiates a peer pull and prints the resulting URI.- –uri TALER-URI
The
taler://pay/…(preview/pay) ortaler://pay-push/…(push) URI to act on. Required for those operations. The helper validates it again here, at the privileged boundary:preview/payrefuse anything that is not ataler://pay/URI,pushrefuses anything that is nottaler://, and any URI is refused outright if it holds a character outside the RFC 3986 repertoire (so quotes, backslashes and whitespace can never reach the wallet).- –amount CURRENCY:VALUE
The GNU Taler amount, required for
withdrawandpull.- –exchange URL
The exchange base URL for a manual
withdraw(required).- –subject TEXT
An optional payment subject/summary for
pull.- –uid N
Local-user mode: drop to uid N and use that user’s default wallet. Mutually exclusive with –user.
- –user NAME –wallet-db KEY
Shared mode: drop to account NAME and use the wallet database named by the opaque, validated KEY under that account’s home. Both are required together.
- –wallet-cli PATH
Refused with an error. The program that runs as another account is fixed at build time. Otherwise any caller able to name it, which means any code that runs as the
pepsiaccount, could run a program of its choosing as that account.- –pay-option OPT
An extra argument appended to the
payinvocation (repeatable; none is needed, sincehandle-urialready waits for the payment to reach a terminal state);--yesis added topayas well, since a helper run from a stage has nobody to ask.Neither applies to push, which is not a
handle-uricall at all but a two-commandpreparePeerPushCredit/continue-txflow:continue-txrejects those flags outright, and it waits for the credit itself. The options are accepted and ignored on that path, so aWALLET_PAY_OPTIONSset for a self-servicepushhas no effect.
95.1.64.1.5. Exit Status¶
- 0
Success. For
previewthe proposed amount is on standard output; forbalance,withdrawandpullthe report text is on standard output; forpayandpushstandard output is empty.- 2
The operation failed (bad arguments, not setuid-root, a refused account, the price could not be read, or the wallet operation failed). A human-readable diagnostic is written to standard output and standard error.
- 3
The wallet requires KYC (identity verification); the KYC URL is on standard output.
95.1.64.1.6. Security¶
The helper deliberately does no configuration, database or logging work. Its only
privileged action is to become the target user before running the wallet; it
refuses to act as root and, after dropping privilege, verifies that root
cannot be regained. Access to it is gated by the pepsi-wallets group, granted to the
caller through pepsi-stage-auto-pay(1)’s SGID bit and to no one else.
The manual’s Security model chapter (The privilege split) lists every
program that carries a setuid or setgid bit; its Threat model chapter (the
local-user section) states what the helpers may and may not be made to do.
95.1.64.1.7. See Also¶
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. Bugs¶
Report bugs to the Pepsi issue tracker.