[taler-marketing] branch master updated: -work on spec

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository marketing.

The following commit(s) were added to refs/heads/master by this push:
     new c653d31  -work on spec
c653d31 is described below

commit c653d31903a0b4015b503de2ed72d0727e8c06c7
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Nov 8 17:12:14 2022 +0100

    -work on spec
---
 standards/draft-grothoff-taler.xml | 242 +++++++++++++++++++++++++++----------
 1 file changed, 179 insertions(+), 63 deletions(-)

diff --git a/standards/draft-grothoff-taler.xml 
b/standards/draft-grothoff-taler.xml
index b3de617..b723993 100644
--- a/standards/draft-grothoff-taler.xml
+++ b/standards/draft-grothoff-taler.xml
@@ -17,7 +17,7 @@
 <?rfc subcompact="no" ?>
 
 <rfc category="info"
-     docName="draft-grothoff-taler-0"
+     docName="draft-grothoff-taler-01"
      ipr="trust200902">
 
   <front>
@@ -117,12 +117,14 @@
   </t>
   <figure>
   <artwork type="abnf"><![CDATA[
-  taler-URI = ("taler://" / "TALER://") action path-abempty [ "?" opts ]
+  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-name = ALPHA *( ALPHA / DIGIT / "-" / "." / ":" )
   opt-value = *pchar
+  ssid = *pchar
 ]]>
   </artwork>
   </figure>
@@ -146,25 +148,40 @@
   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.
+  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
+  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 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.
+
 </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
+  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
 ]]>
   </artwork>
 </figure>
@@ -179,7 +196,9 @@
     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>The description clearly defines the semantics of the action and optional 
parameters if applicable.</t>
+  <t>The name states the unique name for the action that must be part of the 
URI.</t>
+  <t>The syntax defines the format of the action-specific part of the URI.</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>
@@ -189,10 +208,11 @@ When requesting new entries, careful consideration of the 
following criteria is
 Documents that support requests for new registry entries should
  provide the following information for each entry:
 <list style="symbols">
+<t>Description: A description of the action, including
+   the semantics of the path in the URI if applicable.</t>
 <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>Syntax: summary of the syntax of the URI as a one-liner.</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>
@@ -203,117 +223,214 @@ This document populates the registry with $COUNT 
entries as follows (see
 also <xref target="taler-registry" />).
 </t>
 
-<section anchor="registry-entry-withdraw" title="Withdraw">
+<section anchor="registry-entry-withdraw" title="Action: withdraw">
+<t>
+  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.
+</t>
+<t>
+  The specific arguments of a "withdraw" action are:
+  <list style="symbols">
+    <t>bank_host: hostname of the bank (optionally including a port number)</t>
+    <t>bank_prefix_path: list of path components that identifies the path 
prefix of the bank integration API base URL</t>
+    <t>withdrawal_uid: the unique ID of the withdrawal operation</t>
+  </list>
+</t>
 <t>
 <list style="symbols">
 <t>Name: withdraw</t>
-<t>Description: FIXME
-</t>
-<t>Example: taler://withdraw/example.com/XXX</t>
+<t>Syntax: 
taler://withdraw/{bank_host}{/bank_prefix_path*}/{withdrawal_uid}</t>
+<t>Example: taler://withdraw/bank.example.com/wid</t>
 <t>Contact: N/A</t>
 <t>References: [this.I-D]</t>
 </list>
 </t>
 </section>
 
-<section anchor="registry-entry-pay" title="Pay">
+<section anchor="registry-entry-pay" title="Action: pay">
+<t>
+  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.
+</t>
+<t>
+  The specific arguments of a "pay" action are:
+  <list style="symbols">
+   <t>merchant_host: hostname of the GNU Taler REST service of merchant (may 
optionally include a port number)</t>
+   <t>merchant_prefix_path: list of path components that identifies the path 
prefix of the merchant base URL</t>
+   <t>order_id: the order ID that the customer is asked to pay for</t>
+   <t>session_id:  the session ID under which the payment takes place</t>
+   <t>c: a high-entropy order "ClaimToken"</t> 
+  </list>
+</t>
 <t>
 <list style="symbols">
 <t>Name: pay</t>
-<t>Description:
-</t>
-<t>Example: taler://pay/SOGEDEFFXXX</t>
+<t>Syntax: 
taler://pay/{merchant_host}{/merchant_prefix_path*}/{order_id}/{session_id}{?c}</t>
+<t>Example: taler://pay/merchant.example.com/42/</t>
 <t>Contact: N/A</t>
 <t>References: [this.I-D]</t>
 </list>
 </t>
 </section>
 
-<section anchor="registry-entry-refund" title="Refund">
+<section anchor="registry-entry-refund" title="Action: refund">
+  <t>
+    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.
+  </t>
+  <t>
+  The specific arguments of a "refund" action are:
+  <list style="symbols">
+    <t>merchant_host: hostname of the merchant (possibly including a port 
number)</t>
+    <t>merchant_prefix_path: list of path components that identifies the path 
prefix of the merchant base URL</t>
+    <t>order_id: the order ID to check for refunds</t>
+  </list>
+</t>
 <t>
 <list style="symbols">
 <t>Name: refund</t>
-<t>Description:
-</t>
-<t>Example:
-  taler://refund/
-</t>
+<t>Syntax: 
taler://refund/{merchant_host}{/merchant_prefix_path*}/{order_id}/</t>
+<t>Example: taler://refund/shop.example.com/42/</t>
 <t>Contact: N/A</t>
 <t>References: [this.I-D]</t>
 </list>
 </t>
 </section>
 
-<section anchor="registry-entry-tip" title="tip">
+<section anchor="registry-entry-tip" title="Action: tip">
+  <t>
+    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.
+  </t>
+  <t>
+  The specific arguments of a "tip" action are:
+  <list style="symbols">
+    <t>merchant_host: hostname of the merchant (possibly including a port 
number)</t>
+    <t>merchant_prefix_path: list of path components that identifies the path 
prefix of the merchant base URL</t>
+    <t>tip_id: identifier that uniquely identifies the tip</t>
+  </list>
+</t>
 <t>
 <list style="symbols">
 <t>Name: tip</t>
-<t>Description:
-  </t>
-<t>Example: taler://tip/merchant.com/</t>
+<t>Syntax: taler://tip/{merchant_host}{/merchant_prefix_path*}/{tip_id}/</t>
+<t>Example: taler://tip/merchant.com/FIXME</t>
 <t>Contact: N/A</t>
 <t>References: [this.I-D]</t>
 </list>
 </t>
 </section>
 
-<section anchor="registry-entry-pay-push" title="pay-push">
+<section anchor="registry-entry-pay-push" title="Action: pay-push">
+  <t>
+    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.
+  </t>
+  <t>
+  The specific arguments of a "pay-push" action are:
+  <list style="symbols">
+    <t>exchange_host: the hostname of the exchange (possibly including a port 
number)</t>
+    <t>exchange_prefix_path: list of path components that identifies the path 
prefix of the exchange base URL</t>
+    <t>contract_priv: the private key of the peer push payment contract stored 
at the exchange</t>
+  </list>
+</t>
 <t>
 <list style="symbols">
 <t>Name: pay-push</t>
-<t>Description:
-</t>
-<t>Example: taler://pay-push/bank.com/</t>
+<t>Syntax: 
taler://pay-push/{exchange_host}{/exchange_prefix_path*}/{contract_priv}</t>
+<t>Example: taler://pay-push/exchange.example.com/FIXME</t>
 <t>Contact: N/A</t>
 <t>References: [this.I-D]</t>
 </list>
 </t>
 </section>
 
-<section anchor="registry-entry-pay-pull" title="pay-pull">
+<section anchor="registry-entry-pay-pull" title="Action: pay-pull">
+<t>
+  The specific arguments of a "pay-pull" action are:
+  <list style="symbols">
+    <t>exchange_host: the hostname of the exchange (possibly including a port 
number)</t>
+    <t>exchange_prefix_path: list of path components that identifies the path 
prefix of the exchange base URL</t>
+    <t>XXX: </t>
+  </list>
+</t>
 <t>
 <list style="symbols">
 <t>Name: pay-pull</t>
-<t>Description:
+<t>Syntax:
 </t>
-<t>Example: taler://pay-pull/bank.com/</t>
+<t>Example: taler://pay-pull/exchange.example.com/FIXME</t>
 <t>Contact: N/A</t>
 <t>References: [this.I-D]</t>
 </list>
 </t>
 </section>
 
-<section anchor="registry-entry-exchange" title="exchange">
+<section anchor="registry-entry-exchange" title="Action: exchange">
+<t>
+  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.
+</t>
+<t>
+  The specific arguments of an "exchange" action are:
+  <list style="symbols">
+    <t></t>
+  </list>
+</t>
 <t>
 <list style="symbols">
 <t>Name: exchange</t>
-<t>Description:
-</t>
-<t>Example: taler://exchange/bank.com/</t>
+<t>Syntax: taler://exchange/{exchange_host}{/exchange_prefix_path*}/</t>
+<t>Example: taler://exchange/exchange.example.com/</t>
 <t>Contact: N/A</t>
 <t>References: [this.I-D]</t>
 </list>
 </t>
 </section>
 
-<section anchor="registry-entry-auditor" title="auditor">
+<section anchor="registry-entry-auditor" title="Action: auditor">
+<t>
+  An "auditor" 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 
auditors.
+</t>
+<t>
+  The specific arguments of an "auditor" action are:
+  <list style="symbols">
+    <t></t>
+  </list>
+</t>
 <t>
 <list style="symbols">
 <t>Name: auditor</t>
-<t>Description:
-</t>
-<t>Example: taler://auditor/bank.com/</t>
+<t>Syntax: taler://auditor/{auditor_host}{/auditor_prefix_path*}/</t>
+<t>Example: taler://auditor/auditor.example.com/</t>
 <t>Contact: N/A</t>
 <t>References: [this.I-D]</t>
 </list>
 </t>
 </section>
 
-<section anchor="registry-entry-auditor" title="restore">
+<section anchor="registry-entry-restore" title="Action: restore">
+<t>
+  The specific arguments of a "restore" action are:
+  <list style="symbols">
+    <t></t>
+  </list>
+</t>
 <t>
 <list style="symbols">
 <t>Name: restore</t>
-<t>Description:
+<t>Syntax:
 </t>
 <t>Example: taler://restore/backup.com/KEY</t>
 <t>Contact: N/A</t>
@@ -322,13 +439,19 @@ also <xref target="taler-registry" />).
 </t>
 </section>
 
-<section anchor="registry-entry-error" title="error">
+<section anchor="registry-entry-error" title="Action: error">
 <t>
-<list style="symbols">
-<t>Name: error</t>
+</t>
 <t>
-  Description:
+  The specific arguments of an "error" action are:
+  <list style="symbols">
+    <t></t>
+  </list>
 </t>
+<t>
+<list style="symbols">
+<t>Name: error</t>
+<t>Syntax: payto://error/{name}</t>
 <t>Example: payto://error/xxx</t>
 <t>Contact: N/A</t>
 <t>References: [this.I-D]</t>
@@ -561,14 +684,7 @@ dots and dashes)</t>
   </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
+v00 2022-11-xx  CG   Initial version
   -->
 </back>
 </rfc>

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.