Independent Stream C.G. Grothoff Internet-Draft BFH Intended status: Informational F.D. Dold Expires: 15 May 2023 Taler Systems SA 11 November 2022 The 'taler' URI scheme for GNU Taler Wallet interactions draft-grothoff-taler-00 Abstract This document defines the 'taler' Uniform Resource Identifier (URI) scheme for triggering interactions with a GNU Taler wallet. This URI scheme allows applications to trigger interactions with the GNU Taler wallet, such as withdrawing money, making payments, receiving refunds and restoring a wallet from a backup. Applications may receive such URIs in many ways (including via NFC, QR codes, Web links or messaging applications), or might generate them internally to interact with a wallet. By having a Taler wallet handle the respective URIs, applications can integrate Taler payments without having to support the Taler protocol directly. Furthermore, by passing control to a Taler wallet process, the wallet's database with its financial data might be better protected from application failures. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 15 May 2023. Copyright Notice Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved. Grothoff & Dold Expires 15 May 2023 [Page 1] Internet-Draft The 'taler' URI scheme November 2022 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Objective . . . . . . . . . . . . . . . . . . . . . . . . 2 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 3 2. Syntax of a 'taler' URI . . . . . . . . . . . . . . . . . . . 3 3. Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4 5. Tracking Taler URI Actions . . . . . . . . . . . . . . . . . 4 5.1. Action: withdraw . . . . . . . . . . . . . . . . . . . . 5 5.2. Action: pay . . . . . . . . . . . . . . . . . . . . . . . 6 5.3. Action: refund . . . . . . . . . . . . . . . . . . . . . 6 5.4. Action: tip . . . . . . . . . . . . . . . . . . . . . . . 7 5.5. Action: pay-push . . . . . . . . . . . . . . . . . . . . 7 5.6. Action: pay-pull . . . . . . . . . . . . . . . . . . . . 8 5.7. Action: pay-template . . . . . . . . . . . . . . . . . . 9 5.8. Action: exchange . . . . . . . . . . . . . . . . . . . . 10 5.9. Action: auditor . . . . . . . . . . . . . . . . . . . . . 10 5.10. Action: restore . . . . . . . . . . . . . . . . . . . . . 11 5.11. Action: dev-experiment . . . . . . . . . . . . . . . . . 11 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 7.1. URI Scheme Registration . . . . . . . . . . . . . . . . . 12 8. Taler URI Actions . . . . . . . . . . . . . . . . . . . . . . 12 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 9.1. Normative References . . . . . . . . . . . . . . . . . . 13 9.2. Informational References . . . . . . . . . . . . . . . . 13 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 1. Introduction This document defines the 'taler' Uniform Resource Identifier (URI) [RFC3986] scheme for triggering interactions with GNU Taler wallets. 1.1. Objective A 'taler' URI always instructs a GNU Taler wallet to perform a particular operation. A 'taler' URI consists of an action and optional parameters. Grothoff & Dold Expires 15 May 2023 [Page 2] Internet-Draft The 'taler' URI scheme November 2022 The interpretation of the optional parameters depends on the action. 1.2. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 2. Syntax of a 'taler' URI This document uses the Augmented Backus-Naur Form (ABNF) of [RFC5234]. taler-URI = ("taler://" / "TALER://" / "taler+http" / "TALER+HTTP" ) action path-abempty [ "?" opts ] ["#" ssid ] action = ALPHA *( ALPHA / DIGIT / "-" / "." ) opts = opt *( "&" opt ) opt = opt-name "=" opt-value opt-name = ALPHA *( ALPHA / DIGIT / "-" / "." / ":" ) opt-value = *pchar ssid = *pchar 'path-abempty' is defined in [RFC3986] in Section 3.3. 'pchar' is defined in [RFC3986], Appendix A. 3. Semantics The action of a Taler URI identifies the operation requested from the Taler wallet. Actions are not case-sensitive. The actions are defined in the "Taler URI Actions" sub-registry, see Section 8. The path component of the URI typically provides a network address needed to locate additional information or services relevant to the requested operation. Paths are case-sensitive, but may contain case- insensitive portions, such as domain names. The query component of the URI provides immediate additional parameters or options for the operation. The query is case-sensitive. The default operation of applications that invoke a URI with the taler scheme MUST be to launch a Taler wallet (if available). If no taler URI handler is available, an application SHOULD show a QR code with the contents of the URI. If multiple Taler wallets are registered, the user SHOULD be able to choose which application to launch. This allows users with multiple wallets (each possibly with its own money) to choose which wallet to perform the operation with. An application SHOULD allow dereferencing a "taler://" URI even if the action of that URI is not registered in the "Taler URI Actions" sub-registry. Wallets Grothoff & Dold Expires 15 May 2023 [Page 3] Internet-Draft The 'taler' URI scheme November 2022 seeing a "taler://" URI MUST use HTTP over TLS when talking to the respective network service. Wallets seeing a "taler+http://" URI MUST use HTTP without TLS when talking to the respective network service. Wallets SHOULD support "taler+http://"-URIs only when run in developer or debug mode. Any taler://-URI may include an optional "ssid" argument after the optional "#" character. If present, the "ssid" must be the SSID of an open wireless network in the vicinity that the wallet application may use to process the request. 4. Examples taler://pay/example.com/2022.268-03G33PTAY2C6T/\ 00f68430-363a-46b7-8e33-241a0e49c430?c=KKBWMSTF4AZSP8XS0FFNE9KM5M taler://pay-push/bank.example.com/\ 3BBW6N8PVDYBRT0DERT8YYARQGFYHVQFG3WVAN1D58FRP5JG3M4G TALER://PAY-PULL/BANK.EXAMPLE.COM/\ WB361HXN7BZ9ND1B9YP1Y20NB4H5WS0RNM4K8AFZ5Q2VRW577BPG 5. Tracking Taler URI Actions A registry of Taler URI Actions is described in Section 8. The registration policy for this registry is "Expert Review", as described in [RFC8126]. When requesting new entries, careful consideration of the following criteria is strongly advised: 1. The description clearly defines the semantics of the action and optional parameters if applicable. 2. The name states the unique name for the action that must be part of the URI. 3. The syntax defines the format of the action-specific part of the URI. 4. Relevant references are provided if they are available. 5. The chosen name is appropriate for the operation, and avoids potential to confuse users. 6. A libre software reference implementation is available. Documents that support requests for new registry entries should provide the following information for each entry: * Description: A description of the action, including the semantics of the path in the URI if applicable. Grothoff & Dold Expires 15 May 2023 [Page 4] Internet-Draft The 'taler' URI scheme November 2022 * Name: The name of the Taler URI action (case insensitive ASCII string, restricted to alphanumeric characters, dots and dashes) * Syntax: summary of the syntax of the URI as a one-liner. * Example: At least one example URI to illustrate the action. * Contact: The contact information of a person to contact for further information * References: Optionally, references describing the action (such as an RFC) and target-specific options. This document populates the registry with $COUNT entries as follows (see also Section 8). 5.1. Action: withdraw The action "withdraw" is used to trigger a bank-integrated withdrawal operation. This means that the user has been interacting with some online banking App and wants to instruct the bank to transfer money from the user's bank account into a the GNU Taler wallet. The wallet now needs to allow the user to select the GNU Taler exchange, and then ultimately provide the bank with its reserve public key and await the completion of the wire transfer. The specific arguments of a "withdraw" action are: * bank_host: hostname of the bank (optionally including a port number) * bank_prefix_path: list of path components that identifies the path prefix of the bank integration API base URL * withdrawal_uid: the unique ID of the withdrawal operation * Name: withdraw * Syntax: taler://withdraw/{bank_host}{/bank_prefix_path*}/{withdrawal_uid} * Example: taler://withdraw/bank.example.com/wid * Contact: N/A * References: [this.I-D] Grothoff & Dold Expires 15 May 2023 [Page 5] Internet-Draft The 'taler' URI scheme November 2022 5.2. Action: pay Payments are requested with the "pay" action. The parameters are a hierarchical identifier for the requested payment, and must include a hostname, order ID and session ID (which may be an empty string). Additionally, a claim token and a prefix path to be used as part of the HTTP REST API request to the hostname may be specified. The specific arguments of a "pay" action are: * merchant_host: hostname of the GNU Taler REST service of merchant (may optionally include a port number) * merchant_prefix_path: list of path components that identifies the path prefix of the merchant base URL * order_id: the order ID that the customer is asked to pay for * session_id: the session ID under which the payment takes place * ct: a high-entropy order "ClaimToken" * Name: pay * Syntax: taler://pay/{merchant_host}{/merchant_prefix_path*}/{order _id}/{session_id}{?c=ct} * Example: taler://pay/merchant.example.com/42/ * Contact: N/A * References: [this.I-D] 5.3. Action: refund A "refund" action instructs the wallet to download information about an available refund, possibly consult the user about the refund, and then obtain the refund for an already paid order. The specific arguments of a "refund" action are: * merchant_host: hostname of the merchant (possibly including a port number) * merchant_prefix_path: list of path components that identifies the path prefix of the merchant base URL * order_id: the order ID to check for refunds Grothoff & Dold Expires 15 May 2023 [Page 6] Internet-Draft The 'taler' URI scheme November 2022 * Name: refund * Syntax: taler://refund/{merchant_host}{/merchant_prefix_path*}/{order_id}/ * Example: taler://refund/shop.example.com/42/ * Contact: N/A * References: [this.I-D] 5.4. Action: tip A tipping URI instructs the wallet to download information about a tip from a merchant and to ask the user to accept/decline the tip. The specific arguments of a "tip" action are: * merchant_host: hostname of the merchant (possibly including a port number) * merchant_prefix_path: list of path components that identifies the path prefix of the merchant base URL * tip_id: identifier that uniquely identifies the tip * Name: tip * Syntax: taler://tip/{merchant_host}{/merchant_prefix_path*}/{tip_id}/ * Example: taler://tip/merchant.com/FIXME * Contact: N/A * References: [this.I-D] 5.5. Action: pay-push A pay-push URI instructs the wallet to ask the user about accepting a P2P payment. The wallet should download, decrypt and display the underlying contract and accept the offered money if the user agrees to the contract. The specific arguments of a "pay-push" action are: * exchange_host: the hostname of the exchange (possibly including a port number) Grothoff & Dold Expires 15 May 2023 [Page 7] Internet-Draft The 'taler' URI scheme November 2022 * exchange_prefix_path: list of path components that identifies the path prefix of the exchange base URL * merge_priv: private key that grants the capability to take the money in the purse * Name: pay-push * Syntax: taler://pay- push/{exchange_host}{/exchange_prefix_path*}/{merge_priv} * Example: taler://pay-push/exchange.example.com/ KAMRGDM8FNQ82HSBVDEH8MCAF13Q0B51P4R35RFG2CBVHKGT321G * Contact: N/A * References: [this.I-D] 5.6. Action: pay-pull A pay-pull URI instructs the wallet about a request made to the user to pay an invoice (or to simply send money to another wallet). The wallet should download, decrypt and display the underlying contract and ask the user if they agree to pay the invoice. The specific arguments of a "pay-pull" action are: * exchange_host: the hostname of the exchange (possibly including a port number) * exchange_prefix_path: list of path components that identifies the path prefix of the exchange base URL * contract_priv: the private key of the peer push payment contract stored at the exchange * Name: pay-pull * Syntax: taler://pay- pull/{exchange_host}{/exchange_prefix_path*}/{contract_priv} * Example: taler://pay-pull/exchange.example.com/ PN3W8SN6N8V1V5MTEZRPJJ2ANY8GGZMB1MBXC7NMSRXJN6MZ5SWG * Contact: N/A * References: [this.I-D] Grothoff & Dold Expires 15 May 2023 [Page 8] Internet-Draft The 'taler' URI scheme November 2022 5.7. Action: pay-template A "pay-template" action instructs the wallet to ask its user to manually complete an order template and submit the information to the merchant to obtain a "pay" request. Contract fields that are not specified in the argument list must not be submitted. Wallets do not have to support users entering all possible fields of a contract. Keys that MUST be supported at this time are the "amount" and the "summary" fields. The wallet MUST validate that the amount entered by the user is well-formed. For the amount, it is possible that the QR code already specifies the currency (e.g. "amount=CHF" or "amount=CHF:5") in which case the wallet MUST only allow the user to enter an amount in that currency. If the amount entered by the user exceeds the wallet balance, the wallet SHOULD NOT allow the user to submit the action. A QR code may not specify any keys for manual entry. In this case, the wallet MUST immediately submit the request (with an empty body) to the merchant to obtain a dynamically generated "taler://pay/" URI based on the template. The specific arguments of a "pay-template" action is: * merchant_host: hostname of the merchant * merchant_prefix_path: list of path components that identifies the path prefix of the merchant base URL * template_id: identifier that uniquely identifies the template * key: possible contract detail to prompt the user for * value: default value to use for the respective key * Name: pay-template * Syntax: taler://pay-template/{merchant_host}{/merchant_prefix_path *}/{template_id}[?key[=value]}{&key[=value]}* * Example: taler://pay-template/merchant.example.com/ FEGHYJY48FEGU6WETYIOIDEDE2QW3OCZVY?amount=KUDOS:5 * Contact: N/A * References: [this.I-D] Grothoff & Dold Expires 15 May 2023 [Page 9] Internet-Draft The 'taler' URI scheme November 2022 5.8. Action: exchange An "exchange" action instructs the wallet to display a prompt to the user, asking the user to confirm/decline adding the exchange to the list of trusted exchanges. The specific arguments of an "exchange" action are: * exchange_host: hostname of the exchange (possibly including a port number) * exchange_prefix_path: list of path components that identifies the path prefix of the exchange base URL * Name: exchange * Syntax: taler://exchange/{exchange_host}{/exchange_prefix_path*}/ * Example: taler://exchange/exchange.example.com/ * Contact: N/A * References: [this.I-D] 5.9. Action: auditor An "auditor" action instructs the wallet to display a prompt to the user, asking the user to confirm/decline adding the auditor to the list of trusted auditors. The specific arguments of an "auditor" action are: * auditor_host: the hostname of the auditor (possibly including a port number) * auditor_prefix_path: list of path components that identifies the path prefix of the auditor base URL * Name: auditor * Syntax: taler://auditor/{auditor_host}{/auditor_prefix_path*}/ * Example: taler://auditor/auditor.example.com/ * Contact: N/A * References: [this.I-D] Grothoff & Dold Expires 15 May 2023 [Page 10] Internet-Draft The 'taler' URI scheme November 2022 5.10. Action: restore A "restore" action instructs the wallet to restore a wallet backup and merge it into its current state. The specific arguments of a "restore" action are: * sync_rootkey: Root sync key of the wallet, used to derive the symmetric key to encrypt the backup with individual providers. * sync_provider_list: Comma-separated list of provider http or https URLs. If no scheme part is specified, https is assumed. Each URL is URI-encoded for all characters except "A-Z a-z 0-9 - _ . ! ~ * ' ( )" (matching the HTML5 encodeURIComponent). * Name: restore * Syntax: taler://auditor/{sync_rootkey}/{sync_provider_list} * Example: taler://restore/backup.example.com/ GJKG23V4ZBHEH45YRK7TWQE8ZTY7JWTY5094TQJSRZN5DSDBX8E0/ prov1.example.com,prov2.example.com * Contact: N/A * References: [this.I-D] 5.11. Action: dev-experiment An "dev-experiment" action instructs the wallet to simulate a particular error scenario. This action can be used to test the user interface. Wallets that are not in developer mode should not run the specified action and instead inform the user that "dev-experiment" actions are only supported in developer mode. The specific arguments of a "dev-experiment" action are: * name: specifies the specific type of dev experiment * Name: dev-experiment * Syntax: payto://dev-experiment/{name} * Example: payto://dev-experiment/xxx * Contact: N/A * References: [this.I-D] Grothoff & Dold Expires 15 May 2023 [Page 11] Internet-Draft The 'taler' URI scheme November 2022 6. Security Considerations Interactive applications handling the taler URI scheme MUST NOT initiate any unsafe payment operations prior review and confirmation from the user, and MUST take measures to prevent clickjacking [HMW12]. The authentication/authorization mechanisms and transport security services used to process a payment encoded in a taler URI are handled by the application and are not in scope of this document. 7. IANA Considerations IANA maintains a registry called the "Uniform Resource Identifier (URI) Schemes" registry. 7.1. URI Scheme Registration IANA maintains the "Uniform Resource Identifier (URI) Schemes" registry that contains an entry for the 'taler' URI scheme. IANA is requested to update that entry to reference this document when published as an RFC. 8. Taler URI Actions This document specifies a list of Taler URI Actions. It is possible that future work will need to specify additional actions. The GNUnet Assigned Numbers Authority (GANA) [GANA] operates the "taler-uri- actions" registry to track the following information for each payment target type: * Name: The name of the action (case insensitive ASCII string, restricted to alphanumeric characters, dots and dashes) * Contact: The contact information of a person to contact for further information * References: Optionally, references describing the payment target type (such as an RFC) and target-specific options, or references describing the payment system underlying the payment target type. The entries that have been made for the "taler-uri-actions" defined in this document are as follows: Grothoff & Dold Expires 15 May 2023 [Page 12] Internet-Draft The 'taler' URI scheme November 2022 Name | Contact | Reference ---------------+-------------------------+------------ pay | N/A | [This.I-D] withdraw | N/A | [This.I-D] refund | N/A | [This.I-D] tip | N/A | [This.I-D] pay-pull | N/A | [This.I-D] pay-push | N/A | [This.I-D] pay-template | N/A | [This.I-D] exchange | N/A | [This.I-D] auditor | N/A | [This.I-D] restore | N/A | [This.I-D] dev-experiment | N/A | [This.I-D] 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 9.2. Informational References [GANA] GNUnet e.V., "GNUnet Assigned Numbers Authority (GANA)", April 2020, . Grothoff & Dold Expires 15 May 2023 [Page 13] Internet-Draft The 'taler' URI scheme November 2022 [HMW12] Huang, L.S., Moshchuk, A., Wang, H.J., Schecter, S., and C. Jackson, "Clickjacking: Attacks and Defenses", January 2012, . Authors' Addresses Christian Grothoff BFH Höheweg 80 CH-2501 Biel/Bienne Switzerland Email: christian.grothoff@bfh.ch Florian Dold Taler Systems SA 7, rue de Mondorf L-5421 Erpeldange Luxembourg Email: dold@taler.net Grothoff & Dold Expires 15 May 2023 [Page 14]