95.1.64. pepsi-helper-auto-pay

drive taler-wallet-cli as the paying user

Section du manuel:

1

95.1.64.1.1. Nom

pepsi-helper-auto-pay - helper privilégié qui tarife ou paie une demande de remise GNU Taler en exécutant taler-wallet-cli en tant que l’utilisateur approprié.

95.1.64.1.2. Synopsis

pepsi-helper-auto-pay OP ( –uid N | –user NAME –wallet-db KEY ) [OP-OPTIONS]

où OP est l’un de preview/pay –uri TALER-URI [–pay-option OPT]…, balance, withdraw –amount CURRENCY:VALUE –exchange URL, push –uri TALER-URI, ou pull –amount CURRENCY:VALUE [–subject TEXT].

95.1.64.1.3. Description

pepsi-helper-auto-pay est un helper minimal et durci en sécurité qui exécute taler-wallet-cli contre exactement un wallet, en tant qu’exactement un utilisateur, pour une seule opération de wallet. Il existe afin qu’un appelant de confiance mais non privilégié (un membre du groupe pepsi-wallets, en pratique pepsi-stage-auto-pay(1)) puisse utiliser le bon wallet, et ne rien faire d’autre.

Les opérations prises en charge sont : preview (tarifer une demande taler://pay/… sans payer) et pay (en régler une) pour le rôle entrant de paiement des demandes ; et balance, withdraw (mettre en place un rechargement manuel contre un exchange), push (accepter un paiement pair entrant taler://pay-push/…) et pull (initier un pull pair, produisant une URI taler://pay-pull/…) pour le rôle self-service de wallet.

Le helper est installé setuid-root, possédé root:pepsi-wallets avec le mode 4750. Seuls les membres du groupe pepsi-wallets peuvent l’exécuter ; lorsqu’ils le font, le noyau l’exécute avec un uid effectif de root. Le helper, ensuite :

  1. résout le compte cible et, en mode partagé, le chemin de la base de données du wallet à l’intérieur du répertoire personnel de ce compte, construit à partir du KEY validé (le chemin ne peut donc jamais sortir du répertoire personnel) ;

  2. abandonne complètement et irréversiblement ses privilèges au profit de l’utilisateur cible : il installe les groupes supplémentaires de l’utilisateur, puis règle le gid, puis l’uid (réel, effectif et sauvegardé), et vérifie que root ne peut pas être regagné. Il refuse l’uid 0 et le login root. En mode local-user, il refuse aussi tout uid inférieur à UID_MIN de /etc/login.defs (1000 lorsque ce fichier ne peut pas être lu), parce qu’on y attend un véritable destinataire. Le mode shared en est exempté, puisque sa cible est le compte de service WALLET_USER que l’opérateur a configuré (par exemple pepsi-wallets, typiquement avec un uid bas). Dans ce mode, le groupe principal du compte doit au contraire être le groupe de l’exécutable de ce helper (pepsi-wallets), qu’aucun compte système n’a. Comme pepsi-helper-dot-forward(1) et pepsi-helper-maildir-writer(1), le helper se dépouille complètement de root ;

  3. exécute taler-wallet-cli pour l’opération demandée (en mode partagé avec --wallet-db=…). Le programme est toujours celui de tout le système, fixé à la compilation du helper (/usr/bin/taler-wallet-cli par défaut ; make TALER_WALLET_CLI=… ou ./configure --with-taler-wallet-cli=…). Le helper ne l’exécute qu’après avoir vérifié que lui et chaque répertoire au-dessus appartiennent à root et ne sont modifiables par personne d’autre ; il ne le prend jamais de la ligne de commande, de l’environnement ou de la configuration. Son environnement est construit de zéro, et non filtré : l’enfant ne reçoit que HOME, USER/LOGNAME (le compte cible), un PATH et un SHELL fixes, et rien de ce que l’appelant a passé. À ce stade, les privilèges ont déjà été abandonnés : le chargeur dynamique honore donc de nouveau LD_PRELOAD/LD_AUDIT, et le wallet est un programme Node.js qui honore NODE_OPTIONS/NODE_PATH. L’appelant choisit chaque variable de son propre environnement. Si le helper se contentait de retirer les noms connus comme dangereux, un appelant pourrait encore transformer « exécuter le wallet en tant qu”alice » en « exécuter le code de l’appelant en tant qu”alice ». C’est exactement l’élévation que ce helper existe pour empêcher. L’appelant pourrait aussi rediriger le trafic du wallet vers l’exchange (https_proxy/SSL_CERT_FILE). En mode shared, le répertoire de base de données de wallet ~NAME/wallets est créé avec le mode 0700 s’il est absent.

    preview demande la proposition à wallet-core (api preparePayForUriV2) et lit le prix dans les termes du contrat. handle-uri ne permet pas d’obtenir un prix : sans --yes, il s’arrête à une invite de confirmation qui ne se termine pas sur EOF, et il n’affiche de toute façon aucun prix. pay exécute handle-uri --choice-index 0 --yes plus les éventuels arguments --pay-option supplémentaires et va jusqu’à son terme (un contrat de version 1 propose une liste de choices et ne peut être payé tant qu’un choix n’est pas nommé ; le premier est celui dont preview a donné le prix). push demande deux commandes de wallet : preparePeerPushCredit de wallet-core (api) pour enregistrer le paiement entrant et obtenir son identifiant de transaction, puis continue-tx --yes --wait pour l’accepter. (Pour une telle URI, handle-uri demande une confirmation quoi que dise --yes, et échoue sans terminal.) pull exécute peer-request, et balance et withdraw les sous-commandes de même nom ; chacune rapporte son résultat (l’URI pay-pull, le texte du solde, ou les instructions de virement du retrait). Seules les sous-commandes taler-wallet-cli exactes dépendent de la version du wallet, et elles restent confinées dans le helper.

Les deux opérations entre pairs attendent la boucle de tâches du wallet. peer-request rend la main dès que la purse est auprès de l’exchange ; avant cela, l’URI que reçoit l’utilisateur n’est pas payable du tout, et rien d’autre ne créerait jamais la purse, puisqu’un wallet par utilisateur ne se réveille que lorsque son propriétaire envoie la commande suivante. Le helper lui accorde 60 secondes et signale un échec au-delà. Un push accepté est attendu jusqu’à ce qu’il soit final, 30 secondes au plus, afin que ses pièces soient dépensables plutôt qu’en attente. Chaque attente se termine en général en une ou deux secondes ; les limites s’appliquent lorsque l’exchange est injoignable ou exige d’abord une vérification KYC. Le helper a besoin d’un taler-wallet-cli disposant de peer-request et de continue-tx (1.6.46 et suivants).

Si le wallet signale une exigence KYC (vérification d’identité) pour une opération self-service, le helper extrait l’URL KYC et quitte avec 3 en plaçant l’URL sur la sortie standard, afin que l’étape puisse envoyer le lien par e-mail à l’utilisateur. Le helper ne cherche un KYC que si l’opération n’a produit aucun résultat propre : une opération réussie est rapportée comme un succès même si la sortie de diagnostic du wallet mentionne KYC quelque part, et l’URL est prise dans le texte qui mentionne KYC plutôt qu’à l’endroit où une URL apparaît en premier.

L’appelant choisit l’un des deux modèles de compte. Avec –uid, le helper abandonne ses privilèges au profit de cet uid local et utilise le wallet par défaut de cet utilisateur (WALLET_MODE = local-user dans pepsi-stage-auto-pay(1)). Avec –user et –wallet-db, il abandonne ses privilèges au profit du compte partagé nommé (par défaut pepsi-wallets) et pointe le wallet vers ~NAME/wallets/KEY.sqlite3 (WALLET_MODE = shared). Un wallet laissé sous le nom KEY.json, un format que le taler-wallet-cli actuel n’ouvre plus, n’est pas migré : le helper avertit sur la sortie d’erreur standard et démarre un nouveau wallet à côté.

Ce programme n’est pas destiné à être exécuté à la main ; c’est pepsi-stage-auto-pay(1) qui l’invoque. Il est documenté ici en raison de son installation privilégiée.

95.1.64.1.4. Options

preview | pay | balance | withdraw | push | pull

L’opération. preview affiche le prix d’une demande sans payer ; pay la règle ; balance affiche le solde du wallet ; withdraw met en place un rechargement manuel et affiche les instructions de virement ; push accepte un paiement pair entrant ; pull initie un pull pair et affiche l’URI résultante.

–uri TALER-URI

L’URI taler://pay/… (preview/pay) ou taler://pay-push/… (push) sur laquelle agir. Obligatoire pour ces opérations. Le helper la valide de nouveau ici, à la frontière privilégiée : preview/pay refusent tout ce qui n’est pas une URI taler://pay/, push refuse tout ce qui n’est pas taler://, et toute URI est refusée d’emblée si elle contient un caractère hors du répertoire de la RFC 3986 (de sorte que guillemets, barres obliques inverses et espaces ne puissent jamais atteindre le wallet).

–amount CURRENCY:VALUE

Le montant GNU Taler, requis pour withdraw et pull.

–exchange URL

L’URL de base de l’exchange pour un withdraw manuel (requise).

–subject TEXT

Un objet/résumé de paiement facultatif pour pull.

–uid N

Mode local-user : abandonne les privilèges vers l’uid N et utilise le wallet par défaut de cet utilisateur. Mutuellement exclusif avec –user.

–user NAME –wallet-db KEY

Mode partagé : abandonne les privilèges vers le compte NAME et utilise la base de données de wallet nommée par le KEY opaque et validé sous le répertoire personnel de ce compte. Les deux sont requis ensemble.

–wallet-cli PATH

Refusé avec une erreur. Le programme qui s’exécute sous un autre compte est fixé à la compilation. Sinon, tout appelant capable de le nommer, c’est-à-dire tout code qui s’exécute sous le compte pepsi, pourrait exécuter un programme de son choix sous ce compte.

–pay-option OPT

Un argument supplémentaire ajouté à l’invocation pay (répétable ; aucun n’est nécessaire, puisque handle-uri attend déjà que le paiement atteigne un état terminal) ; --yes est également ajouté à pay, puisqu’un helper lancé depuis une étape n’a personne à qui demander.

Ni l’un ni l’autre ne s’applique à push, qui n’est pas du tout un appel handle-uri mais un enchaînement de deux commandes, preparePeerPushCredit / continue-tx : continue-tx rejette purement et simplement ces indicateurs, et attend lui-même le crédit. Les options sont acceptées et ignorées sur ce chemin, de sorte qu’un WALLET_PAY_OPTIONS défini pour un push self-service n’a aucun effet.

95.1.64.1.5. Code de sortie

0

Succès. Pour preview, le montant proposé est sur la sortie standard ; pour balance, withdraw et pull, le texte du rapport est sur la sortie standard ; pour pay et push, la sortie standard est vide.

2

L’opération a échoué (mauvais arguments, pas setuid-root, un compte refusé, le prix n’a pas pu être lu, ou l’opération de wallet a échoué). Un diagnostic lisible par un humain est écrit sur la sortie standard et sur l’erreur standard.

3

Le wallet exige un KYC (vérification d’identité) ; l’URL KYC est sur la sortie standard.

95.1.64.1.6. Sécurité

Le helper ne fait délibérément aucun travail de configuration, de base de données ou de journalisation. Sa seule action privilégiée est de devenir l’utilisateur cible avant d’exécuter le wallet ; il refuse d’agir en tant que root et, après avoir abandonné ses privilèges, vérifie que root ne peut pas être regagné. L’accès au helper est contrôlé par le groupe pepsi-wallets, accordé à l’appelant via le bit SGID de pepsi-stage-auto-pay(1) et à personne d’autre. Le chapitre Modèle de sécurité du manuel (The privilege split) énumère chaque programme qui porte un bit setuid ou setgid ; son chapitre Modèle de menace (la section sur l’utilisateur local) énonce ce qu’on peut ou ne peut pas faire faire aux helpers.

95.1.64.1.7. Voir aussi

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

Signalez les bogues au gestionnaire de tickets de Pepsi.