commit fb6ac66b6e3cd516a13b01d8d7d07cf4f398e5c1
parent 58f693480d6e526c81ba79008dc228cd46ba61d6
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 25 Sep 2022 00:59:06 +0200
draft for taler://
Diffstat:
2 files changed, 576 insertions(+), 1 deletion(-)
diff --git a/standards/Makefile b/standards/Makefile
@@ -2,7 +2,8 @@ all: txt html
html:
xml2rfc --html draft-dold-payto.xml
+ xml2rfc --html draft-grothoff-taler.xml
txt:
xml2rfc draft-dold-payto.xml
-
+ xml2rfc draft-grothoff-taler.xml
diff --git a/standards/draft-grothoff-taler.xml b/standards/draft-grothoff-taler.xml
@@ -0,0 +1,574 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
+<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
+<!ENTITY RFC3629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml">
+<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
+<!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
+<!ENTITY RFC8174 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8174.xml">
+<!ENTITY RFC8126 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8126.xml">
+]>
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
+
+<?rfc strict="yes" ?>
+<?rfc toc="yes" ?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes" ?>
+<?rfc compact="yes" ?>
+<?rfc subcompact="no" ?>
+
+<rfc category="info"
+ docName="draft-grothoff-taler-0"
+ ipr="trust200902">
+
+ <front>
+ <title abbrev="The 'taler' URI scheme">
+ The 'taler' URI scheme for GNU Taler Wallet interactions
+ </title>
+
+ <author fullname="Christian Grothoff" initials="C.G." surname="Grothoff">
+ <organization>BFH</organization>
+ <address>
+ <postal>
+ <street>Höheweg 80</street>
+ <street></street>
+ <city>Biel/Bienne</city>
+ <code>CH-2501</code>
+ <country>CH</country>
+ </postal>
+ <email>christian.grothoff@bfh.ch</email>
+ </address>
+ </author>
+
+ <author fullname="Florian Dold" initials="F.D." surname="Dold">
+ <organization>Taler Systems SA</organization>
+ <address>
+ <postal>
+ <street>7, rue de Mondorf</street>
+ <city>Erpeldange</city>
+ <code>L-5421</code>
+ <country>LU</country>
+ </postal>
+ <email>dold@taler.net</email>
+ </address>
+ </author>
+
+ <date day="01" month="August" year="2022" />
+
+ <!-- Meta-data Declarations -->
+ <area>General</area>
+ <workgroup>Independent Stream</workgroup>
+ <keyword>payments</keyword>
+
+ <abstract>
+
+ <t>
+ This document defines the 'taler' Uniform Resource Identifier (URI) scheme
+ for triggering interactions with a GNU Taler wallet.
+ </t>
+
+ <t>
+ 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 finanical data might be better protected from application failures.
+ </t>
+
+ </abstract>
+
+ </front>
+
+ <middle>
+
+<section anchor="introduction" title="Introduction">
+<t>
+ This document defines the 'taler' Uniform Resource Identifier (URI) <xref target="RFC3986" /> scheme
+ for triggering interactions with GNU Taler wallets.
+</t>
+
+<section title="Objective">
+<t>
+ A 'taler' URI always instructs a GNU Taler wallet to perform a particular operation.
+ A 'taler' URI consists of a action and optional parameters.
+</t>
+<t>
+ The interpretation of the optional parameters depends on the action.
+</t>
+</section>
+<section title="Requirements Language">
+<t>
+ 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
+ <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when,
+ they appear in all capitals, as shown here.
+</t>
+</section>
+
+</section>
+
+<section anchor="syntax"
+ title="Syntax of a 'taler' URI">
+ <t>
+ This document uses the Augmented Backus-Naur Form (ABNF) of <xref target="RFC5234"/>.
+ </t>
+ <figure>
+ <artwork type="abnf"><![CDATA[
+ taler-URI = ("taler://" / "TALER://") action path-abempty [ "?" opts ]
+ action = ALPHA *( ALPHA / DIGIT / "-" / "." )
+ opts = opt *( "&" opt )
+ opt = opt-name "=" opt-value
+ opt-name = ALPHA *( ALPHA / DIGIT / "-" / "." )
+ opt-value = *pchar
+]]>
+ </artwork>
+ </figure>
+ <t>
+ 'path-abempty' is defined in <xref target="RFC3986" /> in Section 3.3.
+ 'pchar' is defined in <xref target="RFC3986" />, Appendix A.
+ </t>
+</section>
+
+<section anchor="semantics" title="Semantics">
+<t>
+ 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 <xref target="taler-registry" />.
+
+ 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.
+
+</t>
+</section>
+
+<section anchor="examples" title="Examples">
+<figure>
+ <artwork><![CDATA[
+ taler://pay/example.com/2022.268-03G33PTAY2C6T/00f68430-363a-46b7-8e33-241a0e49c430?c=KKBWMSTF4AZSP8XS0FFNE9KM5M
+ taler://pay-push/bank.com/3BBW6N8PVDYBRT0DERT8YYARQGFYHVQFG3WVAN1D58FRP5JG3M4G
+ TALER://PAY-PULL/BANK.COM/WB361HXN7BZ9ND1B9YP1Y20NB4H5WS0RNM4K8AFZ5Q2VRW577BPG
+]]>
+ </artwork>
+</figure>
+
+</section>
+
+<section anchor="tracking" title="Tracking Taler URI Actions">
+ <t>
+ A registry of Taler URI Actions is described in <xref target="taler-registry" />.
+
+ The registration policy for this registry is "Expert Review",
+ as described in <xref target="RFC8126" />.
+When requesting new entries, careful consideration of the following criteria is strongly advised:
+<list style="numbers">
+ <t>The description clearly defines the syntax and semantics of the action and optional parameters if applicable.</t>
+ <t>Relevant references are provided if they are available.</t>
+ <t>The chosen name is appropriate for the operation, and avoids potential to confuse users.</t>
+ <t>A libre software reference implementation is available.</t>
+</list>
+</t>
+<t>
+Documents that support requests for new registry entries should
+ provide the following information for each entry:
+<list style="symbols">
+<t>Name: The name of the Taler URI action (case insensitive ASCII string, restricted to alphanumeric characters,
+dots and dashes)</t>
+<t>Description: A description of the action, including
+ the semantics of the path in the URI if applicable.</t>
+<t>Example: At least one example URI to illustrate the action.</t>
+<t>Contact: The contact information of a person to contact for further information</t>
+<t>References: Optionally, references describing the action (such as an RFC) and target-specific options.</t>
+</list>
+</t>
+<t>
+This document populates the registry with $COUNT entries as follows (see
+also <xref target="taler-registry" />).
+</t>
+
+<section anchor="registry-entry-withdraw" title="Withdraw">
+<t>
+<list style="symbols">
+<t>Name: withdraw</t>
+<t>Description: FIXME
+</t>
+<t>Example: taler://withdraw/example.com/XXX</t>
+<t>Contact: N/A</t>
+<t>References: [this.I-D]</t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-pay" title="Pay">
+<t>
+<list style="symbols">
+<t>Name: pay</t>
+<t>Description:
+</t>
+<t>Example: taler://pay/SOGEDEFFXXX</t>
+<t>Contact: N/A</t>
+<t>References: [this.I-D]</t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-refund" title="Refund">
+<t>
+<list style="symbols">
+<t>Name: refund</t>
+<t>Description:
+</t>
+<t>Example:
+ taler://refund/
+</t>
+<t>Contact: N/A</t>
+<t>References: [this.I-D]</t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-tip" title="tip">
+<t>
+<list style="symbols">
+<t>Name: tip</t>
+<t>Description:
+ </t>
+<t>Example: taler://tip/merchant.com/</t>
+<t>Contact: N/A</t>
+<t>References: [this.I-D]</t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-pay-push" title="pay-push">
+<t>
+<list style="symbols">
+<t>Name: pay-push</t>
+<t>Description:
+</t>
+<t>Example: taler://pay-push/bank.com/</t>
+<t>Contact: N/A</t>
+<t>References: [this.I-D]</t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-pay-pull" title="pay-pull">
+<t>
+<list style="symbols">
+<t>Name: pay-pull</t>
+<t>Description:
+</t>
+<t>Example: taler://pay-pull/bank.com/</t>
+<t>Contact: N/A</t>
+<t>References: [this.I-D]</t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-exchange" title="exchange">
+<t>
+<list style="symbols">
+<t>Name: exchange</t>
+<t>Description:
+</t>
+<t>Example: taler://exchange/bank.com/</t>
+<t>Contact: N/A</t>
+<t>References: [this.I-D]</t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-auditor" title="auditor">
+<t>
+<list style="symbols">
+<t>Name: auditor</t>
+<t>Description:
+</t>
+<t>Example: taler://auditor/bank.com/</t>
+<t>Contact: N/A</t>
+<t>References: [this.I-D]</t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-auditor" title="restore">
+<t>
+<list style="symbols">
+<t>Name: restore</t>
+<t>Description:
+</t>
+<t>Example: taler://restore/backup.com/KEY</t>
+<t>Contact: N/A</t>
+<t>References: [this.I-D]</t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-error" title="error">
+<t>
+<list style="symbols">
+<t>Name: error</t>
+<t>
+ Description:
+</t>
+<t>Example: payto://error/xxx</t>
+<t>Contact: N/A</t>
+<t>References: [this.I-D]</t>
+</list>
+</t>
+</section>
+
+</section><!-- tracking -->
+
+<section anchor="security" title="Security Considerations">
+<t>
+ 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 <xref target="HMW12"/>.
+</t>
+<t>
+ 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.
+</t>
+</section>
+
+<section anchor="iana" title="IANA Considerations">
+
+<t>
+IANA maintains a registry called the "Uniform Resource Identifier
+(URI) Schemes" registry.
+</t>
+
+<section anchor="payto-uri" title="URI Scheme Registration">
+<t>
+ 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.
+</t>
+</section>
+</section>
+
+<section anchor="taler-registry" title="Taler URI Actions">
+<t>
+ 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) <xref target="GANA" />
+ operates the "taler-uri-actions" registry to track
+ the following information for each payment target type:
+<list style="symbols">
+<t>Name: The name of the action (case insensitive ASCII string, restricted to alphanumeric characters,
+dots and dashes)</t>
+<t>Contact: The contact information of a person to contact for further information</t>
+<t>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.</t>
+</list>
+</t>
+<t>
+ The entries that have been made for the "taler-uri-actions"
+ defined in this document are as follows:
+</t>
+<figure>
+ <artwork>
+ 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]
+ exchange | N/A | [This.I-D]
+ auditor | N/A | [This.I-D]
+ restore | N/A | [This.I-D]
+ error | N/A | [This.I-D]
+ </artwork>
+</figure>
+
+</section><!-- taler-registry -->
+
+</middle>
+
+<back>
+
+ <references title="Normative References">
+
+ &RFC2119;
+
+ &RFC3986;
+
+ &RFC5234;
+
+ &RFC8126;
+
+ &RFC8174;
+
+
+ <reference anchor="ISO4217">
+ <front>
+ <title>ISO 4217 Currency Codes</title>
+ <author>
+ <organization>International Organization for Standardization</organization>
+ <address>
+ <uri>http://www.iso.ch</uri>
+ </address>
+ </author>
+ <date month="August" year="2018"/>
+ </front>
+ </reference>
+
+ <reference anchor="ISO20022">
+ <front>
+ <title>ISO 20022 Financial Services - Universal financial industry message scheme</title>
+ <author>
+ <organization>International Organization for Standardization</organization>
+ <address>
+ <uri>http://www.iso.ch</uri>
+ </address>
+ </author>
+ <date month="May" year="2013"/>
+ </front>
+ </reference>
+
+ <reference anchor="NACHA">
+ <front>
+ <title>NACHA Operating Rules & Guidelines</title>
+ <author>
+ <organization>NACHA</organization>
+ <address>
+ <uri>https://www.nacha.org/</uri>
+ </address>
+ </author>
+ <date month="January" year="2017"/>
+ </front>
+ </reference>
+
+ <reference anchor="unicode-tr36">
+ <front>
+ <title abbrev="Unicode Security Considerations">Unicode Technical Report #36: Unicode Security Considerations</title>
+ <author initials="M." surname="Davis" fullname="Mark Davis" role="editor">
+ <address>
+ <email>markdavis@google.com</email>
+ </address>
+ </author>
+ <author initials="M." surname="Suignard" fullname="Michael Suignard">
+ <address>
+ <email>michel@suignard.com</email>
+ </address>
+ </author>
+ <date month="September" year="2014"/>
+ </front>
+ </reference>
+
+
+ </references>
+
+ <references title="Informational References">
+
+ <reference anchor="BIP0021" target="https://en.bitcoin.it/wiki/BIP_0021">
+ <front>
+ <title>Bitcoin Improvement Proposal 21</title>
+ <author initials="N." surname="Schneider"
+ fullname="Nils Schneider">
+ </author>
+ <author initials="M." surname="Corallo"
+ fullname="Matt Corallo">
+ </author>
+
+ <date month="January" year="2012" />
+ </front>
+ </reference>
+
+ <reference anchor="HMW12" target="https://www.usenix.org/system/files/conference/usenixsecurity12/sec12-final39.pdf">
+ <front>
+ <title>Clickjacking: Attacks and Defenses</title>
+ <author initials="L.S." surname="Huang"
+ fullname="Lin-Shung Huang">
+ </author>
+ <author initials="A." surname="Moshchuk"
+ fullname="Alexander, Moshchuk">
+ </author>
+ <author initials="H.J." surname="Wang"
+ fullname="Helen J. Wang">
+ </author>
+ <author initials="S." surname="Schecter"
+ fullname="Stuart Schecter">
+ </author>
+ <author initials="C." surname="Jackson"
+ fullname="Collin Jackson">
+ </author>
+
+ <date month="January" year="2012" />
+ </front>
+ </reference>
+
+ <reference anchor="UPILinking" target="https://www.npci.org.in/sites/default/files/UPI%20Linking%20Specs_ver%201.6.pdf">
+ <front>
+ <title>Unified Payment Interface - Common URL Specifications For Deep
+ Linking And Proximity Integration</title>
+ <author><organization>National Payment Corporation of India</organization>
+ </author>
+ <date month="November" year="2017" />
+ </front>
+ </reference>
+
+ <reference anchor="ILP-ADDR" target="https://interledger.org/rfcs/0015-ilp-addresses/">
+ <front>
+ <title>ILP Addresses - v2.0.0</title>
+ <author><organization>Interledger Team</organization>
+ </author>
+ <date month="September" year="2018" />
+ </front>
+ </reference>
+
+ <reference anchor="BIC" target="https://www.iso.org/standard/60390.html">
+ <front>
+ <title>ISO 9362:2014 Business Identifier Code (BIC)</title>
+ <author><organization>International Organization for Standardization</organization>
+ </author>
+ <date month="March" year="2019" />
+ </front>
+ </reference>
+
+ <reference anchor="GANA" target="https://gana.gnunet.org/">
+ <front>
+ <title>GNUnet Assigned Numbers Authority (GANA)</title>
+ <author><organization>GNUnet e.V.</organization>
+ </author>
+ <date month="April" year="2020" />
+ </front>
+ </reference>
+
+ </references>
+
+<!-- Change Log
+v11 2020-03-23 CG Workaround IESG/IAB/IANA/ISE discussion on who gets to create IANA registries as suggested by Adrian Farrel
+v10 2019-11-14 CG Address comments from Adrian Farrel
+v09 2019-11-04 CG Reference ISO 4217 for currency codes, clean up ENBF syntax and language (based on feedback from Matthias Heckmann)
+v08 2019-09-27 CG Clarify use of sub-registry as per draft-ise-iana-policy
+v05 2019-05-20 CG Addressing coments, preparing for independent stream submission, adding BIC
+v01 2017-02-15 CG References and formatting
+v01 2017-02-13 CG Minimal clarifications
+v00 2017-01-17 FD Initial version
+ -->
+</back>
+</rfc>
