commit c653d31903a0b4015b503de2ed72d0727e8c06c7
parent e18f6f9eee168ba1149ec028e5563530e955fe41
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 8 Nov 2022 17:12:14 +0100
-work on spec
Diffstat:
1 file changed, 179 insertions(+), 63 deletions(-)
diff --git 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>
